neon 3.0.0 → 3.1.1

package/dist/_chunks/env_services-Tz9G4JeT.js

@@ -0,0 +1,531 @@
+import { NEON_SERVICES } from "../neon_services.js";
+import { ErrorCode, PlatformError, createNeonApiFromOptions, deriveCredentialScopes, resolveConfig } from "@neon/config/v1";
+//#region ../../internals/env-core/dist/env.js
+/**
+* The Neon env core — resolving a branch's env from the Neon API, and projecting it into
+* OS-level `{ KEY: value }` pairs.
+*
+* Private, and bundled into both consumers: `@neon/env` publishes it as `fetchEnv` /
+* `toEntries`, and the `neon` CLI needs the credential-reuse half in `reuse-secrets.ts`.
+* See `README.md` for why it is not published.
+*
+* The counterpart that reads `process.env` — `parseEnv` and its zod schemas — is not here. It
+* has no consumer outside `@neon/env`, so it stays in that package and imports this.
+*/
+/**
+* Mapping between the {@link NeonEnv} property paths and the OS-level env-var keys used
+* for cross-process transport (via `.env` files, `env run -- <cmd>`, or anything else
+* that talks to `process.env`).
+*
+* Each top-level key here is a {@link NeonEnv} namespace; the inner record maps the
+* camelCase property names exposed to TypeScript to the UPPER_SNAKE env-var names used
+* by the OS. Keep this in sync with {@link postgresEnvSchema} / {@link authEnvSchema} /
+* {@link dataApiEnvSchema}.
+*/
+/**
+* Neon's default branch owner role, created with every project. This is the role a
+* `DATABASE_URL` should connect as.
+*/
+const NEON_DEFAULT_OWNER_ROLE = "neondb_owner";
+/**
+* Neon's default database, created with every project. When a branch has several databases
+* and none was requested, this is preferred for the `DATABASE_URL` so the common case (a
+* user added a second database next to `neondb`) auto-picks without asking.
+*/
+const NEON_DEFAULT_DATABASE = "neondb";
+/**
+* Roles Neon provisions for the Auth / Data API (PostgREST) stack. They exist to back
+* RLS-scoped Data API requests authenticated by JWT — never to hold a `DATABASE_URL` —
+* so they're skipped when auto-picking the connection role. Enabling Neon Auth or the
+* Data API (`neon config apply`) adds these next to the owner role, which is why a plain
+* branch routinely reports more than one role.
+*/
+const NEON_MANAGED_AUTH_ROLES = /* @__PURE__ */ new Set([
+	"authenticator",
+	"anonymous",
+	"authenticated"
+]);
+const NEON_ENV_VAR_KEYS = {
+	/**
+	* Branch identity. `NEON_BRANCH` carries the branch **name** and is injected into the
+	* Neon Functions runtime on every branch (including the default) by default. `env pull` /
+	* `neon dev` / `neon-env run` emit it too so local dev mirrors the deployed runtime.
+	*/
+	branch: { name: "NEON_BRANCH" },
+	postgres: {
+		databaseUrl: "DATABASE_URL",
+		databaseUrlUnpooled: "DATABASE_URL_UNPOOLED"
+	},
+	auth: {
+		baseUrl: "NEON_AUTH_BASE_URL",
+		jwksUrl: "NEON_AUTH_JWKS_URL"
+	},
+	dataApi: { url: "NEON_DATA_API_URL" },
+	/**
+	* Object storage (Preview). The S3 SDKs read `AWS_*` from their standard config chain, so
+	* a branch credential + `neon dev` / `env pull` makes object storage work from env alone.
+	* `region` is injected under the SDK-standard `AWS_REGION`.
+	*/
+	storage: {
+		accessKeyId: "AWS_ACCESS_KEY_ID",
+		secretAccessKey: "AWS_SECRET_ACCESS_KEY",
+		endpoint: "AWS_ENDPOINT_URL_S3",
+		region: "AWS_REGION"
+	},
+	/**
+	* AI Gateway (Preview). Exposed under the Neon-branded env vars the deployed Functions
+	* runtime injects: `apiKey` is the minted credential's bearer (`NEON_AI_GATEWAY_TOKEN`)
+	* and `baseUrl` is the bare branch gateway host (`NEON_AI_GATEWAY_BASE_URL`,
+	* `scheme://host`, no path). Clients like `@neon/ai-sdk-provider` read these and append the
+	* dialect route (`/v1`, `/openai/v1`, `/anthropic/v1`) themselves (https://github.com/vercel/ai/pull/15997).
+	*/
+	aiGateway: {
+		apiKey: "NEON_AI_GATEWAY_TOKEN",
+		baseUrl: "NEON_AI_GATEWAY_BASE_URL"
+	}
+};
+/** Fail loudly when selected-key dependency planning and execution disagree. */
+function requiredValue(value, description) {
+	if (value === null) throw new Error(`fetchEnv: missing ${description}.`);
+	return value;
+}
+/**
+* The {@link fetchEnv} body, with the key selection as a plain argument and no generic
+* narrowing. Exists for callers that compute the selection at runtime — notably
+* {@link fetchEnvReusingSecrets}, which decides which keys it still needs by checking the
+* branch — since the public overload's `keys` is bound to a literal union those callers cannot
+* produce without asserting.
+*
+* `keys === null` selects everything the policy enables.
+*/
+async function fetchEnvKeys(config, options, keys) {
+	const api = options.api ?? createApiFromOptions(options);
+	const projectId = options.projectId;
+	const { branch, desired } = await resolveBranchPolicy(config, options, api);
+	const selection = keys ? new Set(keys) : null;
+	const wants = (key) => selection === null || selection.has(key);
+	const result = {};
+	const K = NEON_ENV_VAR_KEYS;
+	const wantsPooled = wants(K.postgres.databaseUrl);
+	const wantsUnpooled = wants(K.postgres.databaseUrlUnpooled);
+	const wantsAuth = desired.authEnabled && (wants(K.auth.baseUrl) || wants(K.auth.jwksUrl));
+	const wantsDataApi = desired.dataApiEnabled && wants(K.dataApi.url);
+	const gatewayEnabled = desired.preview?.aiGatewayEnabled ?? false;
+	const needsUnpooled = wantsUnpooled || gatewayEnabled && wants(K.aiGateway.baseUrl);
+	const needsConnectionTarget = wantsPooled || needsUnpooled;
+	const needsDatabase = needsConnectionTarget || wantsDataApi;
+	const [roles, databases] = await Promise.all([needsConnectionTarget ? api.listBranchRoles(projectId, branch.id) : Promise.resolve([]), needsDatabase ? api.listBranchDatabases(projectId, branch.id) : Promise.resolve([])]);
+	const databaseName = needsDatabase ? pickDatabaseName(databases, branch, options.databaseName) : null;
+	const connectionTarget = needsConnectionTarget ? {
+		roleName: pickRoleName(roles, branch, options.roleName),
+		databaseName: requiredValue(databaseName, "database for a selected connection URI")
+	} : null;
+	const getConnectionUri = (pooled) => {
+		const target = requiredValue(connectionTarget, "role and database for a selected connection URI");
+		return api.getConnectionUri(projectId, {
+			branchId: branch.id,
+			...target,
+			pooled
+		});
+	};
+	const [pooled, unpooled, authSnapshot, dataApiSnapshot] = await Promise.all([
+		wantsPooled ? getConnectionUri(true) : Promise.resolve(null),
+		needsUnpooled ? getConnectionUri(false) : Promise.resolve(null),
+		wantsAuth ? api.getNeonAuth(projectId, branch.id) : Promise.resolve(null),
+		wantsDataApi ? api.getNeonDataApi(projectId, branch.id, requiredValue(databaseName, "database for the selected Data API URL")) : Promise.resolve(null)
+	]);
+	const postgres = {};
+	if (wantsPooled) postgres.databaseUrl = requiredValue(pooled, "pooled connection URI response").uri;
+	if (wantsUnpooled) postgres.databaseUrlUnpooled = requiredValue(unpooled, "direct connection URI response").uri;
+	if (Object.keys(postgres).length > 0) result.postgres = postgres;
+	if (wants(K.branch.name)) result.branch = { name: branch.name };
+	if (wantsAuth) {
+		if (!authSnapshot) throw new PlatformError(ErrorCode.NotFound, [`fetchEnv: branch policy enables auth but no Neon Auth integration is enabled on branch ${branch.name} (${branch.id}).`, "Enable it via `apply(config, { projectId, branchId })` (or `npx neon …`), in the Neon Console — then re-run fetchEnv. Or return auth.enabled=false."].join(" "), { details: {
+			projectId,
+			branchId: branch.id
+		} });
+		const auth = {};
+		if (wants(K.auth.baseUrl)) auth.baseUrl = authSnapshot.baseUrl ?? "";
+		if (wants(K.auth.jwksUrl)) auth.jwksUrl = authSnapshot.jwksUrl ?? "";
+		result.auth = auth;
+	}
+	if (wantsDataApi) {
+		if (!dataApiSnapshot) {
+			const selectedDatabase = requiredValue(databaseName, "database for the selected Data API URL");
+			throw new PlatformError(ErrorCode.NotFound, [`fetchEnv: branch policy enables dataApi but no Data API integration is enabled on branch ${branch.name} (${branch.id}) database ${selectedDatabase}.`, "Enable it via `apply(config, { projectId, branchId })` or in the Neon Console — then re-run fetchEnv. Or return dataApi.enabled=false."].join(" "), { details: {
+				projectId,
+				branchId: branch.id,
+				databaseName: selectedDatabase
+			} });
+		}
+		result.dataApi = { url: dataApiSnapshot.url };
+	}
+	const storageEnabled = (desired.preview?.buckets.length ?? 0) > 0;
+	const wantsStorage = storageEnabled && (wants(K.storage.accessKeyId) || wants(K.storage.secretAccessKey) || wants(K.storage.endpoint) || wants(K.storage.region));
+	const wantsGateway = gatewayEnabled && (wants(K.aiGateway.apiKey) || wants(K.aiGateway.baseUrl));
+	const wantsStorageCredential = storageEnabled && (wants(K.storage.accessKeyId) || wants(K.storage.secretAccessKey));
+	const wantsGatewayCredential = gatewayEnabled && wants(K.aiGateway.apiKey);
+	const wantsCredential = wantsStorageCredential || wantsGatewayCredential;
+	if (wantsStorage || wantsGateway) {
+		let storage = null;
+		if (wantsStorage) {
+			storage = await api.getProjectBranchStorage(projectId, branch.id);
+			if (!storage) throw new PlatformError(ErrorCode.NotFound, [`fetchEnv: branch policy declares object storage (preview.buckets) but storage is not enabled on branch ${branch.name} (${branch.id}).`, "Enable it via `apply(config, { projectId, branchId })` (or in the Neon Console) — then re-run fetchEnv. Or remove preview.buckets."].join(" "), { details: {
+				projectId,
+				branchId: branch.id
+			} });
+		}
+		const secrets = wantsCredential ? await mintBranchCredential({
+			api,
+			projectId,
+			branchId: branch.id,
+			branchName: branch.name,
+			scopes: previewCredentialScopes(desired.preview, {
+				storage: wantsStorageCredential,
+				aiGateway: wantsGatewayCredential
+			})
+		}) : null;
+		if (storage) {
+			const storageEnv = {};
+			if (secrets && wants(K.storage.accessKeyId)) storageEnv.accessKeyId = secrets.accessKeyId;
+			if (secrets && wants(K.storage.secretAccessKey)) storageEnv.secretAccessKey = secrets.secretAccessKey;
+			if (wants(K.storage.endpoint)) storageEnv.endpoint = storage.s3Endpoint;
+			if (wants(K.storage.region)) storageEnv.region = storage.region;
+			result.storage = storageEnv;
+		}
+		if (wantsGateway) {
+			const gateway = {};
+			if (secrets && wants(K.aiGateway.apiKey)) gateway.apiKey = secrets.apiToken;
+			if (wants(K.aiGateway.baseUrl)) gateway.baseUrl = aiGatewayBaseUrl(branch.id, requiredValue(unpooled, "direct connection URI for the selected AI Gateway base URL").uri);
+			result.aiGateway = gateway;
+		}
+	}
+	return result;
+}
+/**
+* Resolve the target branch and evaluate the policy against it — the first thing any
+* branch-scoped operation needs. Shared by {@link fetchEnv} and {@link fetchEnvReusingSecrets}
+* so the two agree on which branch they're talking about and what it has enabled.
+*/
+async function resolveBranchPolicy(config, options, api) {
+	const projectId = options.projectId;
+	const branches = await api.listBranches(projectId);
+	if (branches.length === 0) throw new PlatformError(ErrorCode.BranchNotFound, [`fetchEnv: project ${projectId} has no branches.`, "Deploy your neon.ts policy (or create a branch) first, or pick a different project id."].join(" "), { details: { projectId } });
+	const branchRef = options.branch ?? options.branchId;
+	if (!branchRef) throw new PlatformError(ErrorCode.BranchNotFound, ["fetchEnv: no branch provided.", "Pass `branch` with a branch name (e.g. `main`) or id (`br-…`)."].join(" "), { details: { projectId } });
+	const branch = resolveBranch(branchRef, branches);
+	return {
+		branch,
+		desired: resolveConfig(config, {
+			name: branch.name,
+			id: branch.id,
+			exists: true,
+			...branch.parentId ? { parentId: branch.parentId } : {},
+			isDefault: branch.isDefault,
+			isProtected: branch.protected,
+			...branch.expiresAt ? { expiresAt: branch.expiresAt } : {}
+		})
+	};
+}
+/**
+* Scopes the branch credential should carry for a resolved branch policy and optional key
+* selection. Only object storage and the AI Gateway *require* a credential; functions never
+* force one, but `functions:invoke` rides along when another selected feature mints one.
+*/
+function previewCredentialScopes(preview, selected) {
+	if (!preview) return [];
+	const storage = preview.buckets.length > 0 && (selected?.storage ?? true);
+	const aiGateway = preview.aiGatewayEnabled && (selected?.aiGateway ?? true);
+	if (!storage && !aiGateway) return [];
+	return deriveCredentialScopes({
+		storage,
+		aiGateway,
+		functions: preview.functions.length > 0
+	});
+}
+/** The `name` this tool stamps on every credential it mints, so it can recognize its own. */
+function credentialName(branchName) {
+	return `neon-env ${branchName}`;
+}
+/** The env-var keys a branch credential's secrets surface under, in emit order. */
+function credentialEnvKeys(flags) {
+	return [...flags.storage ? [NEON_ENV_VAR_KEYS.storage.accessKeyId, NEON_ENV_VAR_KEYS.storage.secretAccessKey] : [], ...flags.aiGateway ? [NEON_ENV_VAR_KEYS.aiGateway.apiKey] : []];
+}
+/**
+* Every OS-level env var a resolved branch policy produces, in emit order. Lets a caller
+* subtract the ones it already holds and pass the rest as {@link fetchEnv}'s `keys`, without
+* re-deriving which vars a policy implies.
+*/
+function policyEnvKeys(desired) {
+	const K = NEON_ENV_VAR_KEYS;
+	return [
+		K.postgres.databaseUrl,
+		K.postgres.databaseUrlUnpooled,
+		K.branch.name,
+		...desired.authEnabled ? [K.auth.baseUrl, K.auth.jwksUrl] : [],
+		...desired.dataApiEnabled ? [K.dataApi.url] : [],
+		...(desired.preview?.buckets.length ?? 0) > 0 ? [
+			K.storage.accessKeyId,
+			K.storage.secretAccessKey,
+			K.storage.endpoint,
+			K.storage.region
+		] : [],
+		...desired.preview?.aiGatewayEnabled ? [K.aiGateway.apiKey, K.aiGateway.baseUrl] : []
+	];
+}
+/**
+* Mint the branch credential backing object storage / the AI Gateway.
+*
+* `api_token` and `s3_secret_access_key` come back **exactly once** — they are not stored
+* server-side and the list endpoint returns metadata only — so the caller's copy is the only
+* copy. That is why {@link fetchEnv} mints rather than fetches: there is nothing to fetch. A
+* caller that already holds a valid copy should leave the secret keys out of `keys` (see
+* {@link fetchEnvReusingSecrets}) instead of minting one it will discard.
+*/
+async function mintBranchCredential(args) {
+	const minted = await args.api.createCredential(args.projectId, args.branchId, {
+		scopes: args.scopes,
+		principalType: "user",
+		name: credentialName(args.branchName)
+	});
+	return {
+		accessKeyId: minted.tokenId,
+		secretAccessKey: minted.s3SecretAccessKey,
+		apiToken: minted.apiToken
+	};
+}
+/**
+* The AI Gateway is a **branch-scoped host** — `<branchId>-api.ai.<host-suffix>` — NOT the
+* control-plane API origin. Derive the suffix from the branch's own Postgres connection host
+* by dropping only the endpoint label (the first segment) and keeping everything after it,
+* including any infra cell prefix (`c-N.`): a connection host of
+* `ep-x.c-3.us-east-2.aws.neon.tech` yields the gateway host
+* `<branchId>-api.ai.c-3.us-east-2.aws.neon.tech`. The cell prefix is **load-bearing** —
+* the gateway is cell-routed, so dropping `c-N.` resolves to the wrong (or no) host.
+*/
+function aiGatewayHost(branchId, connectionUri) {
+	let connectionHost = "";
+	try {
+		connectionHost = new URL(connectionUri).hostname;
+	} catch {
+		connectionHost = "";
+	}
+	return `${branchId}-api.ai.${connectionHost.split(".").slice(1).join(".")}`;
+}
+/** The AI Gateway's bare base URL (`NEON_AI_GATEWAY_BASE_URL`) on the branch gateway host. */
+function aiGatewayBaseUrl(branchId, connectionUri) {
+	return `https://${aiGatewayHost(branchId, connectionUri)}`;
+}
+function createApiFromOptions(options) {
+	return createNeonApiFromOptions("fetchEnv", {
+		...options.apiKey ? { apiKey: options.apiKey } : {},
+		...options.apiHost ? { apiHost: options.apiHost } : {}
+	});
+}
+/**
+* Resolve a branch ref — a name or an id — to a concrete branch. Matches by id first
+* (exact `br-…`), then by name; both are unique within a project, so the lookup is
+* unambiguous. This lets `.neon` files written by `neonctl` (which pin the branch *name*)
+* and explicit `br-…` ids both work.
+*/
+function resolveBranch(branch, branches) {
+	const match = branches.find((b) => b.id === branch) ?? branches.find((b) => b.name === branch);
+	if (match) return match;
+	throw new PlatformError(ErrorCode.BranchNotFound, [`fetchEnv: branch ${JSON.stringify(branch)} not found on project (matched by id or name).`, `Existing branches: ${branches.map((b) => `${b.name} (${b.id})`).join(", ")}.`].join(" "), { details: {
+		branch,
+		available: branches.map((b) => `${b.name} (${b.id})`)
+	} });
+}
+function pickRoleName(roles, branch, requested) {
+	if (requested) {
+		if (!roles.some((r) => r.name === requested)) throw new PlatformError(ErrorCode.BranchNotFound, [`fetchEnv: role "${requested}" not found on branch ${branch.name} (${branch.id}).`, `Existing roles: ${roles.map((r) => r.name).join(", ") || "(none)"}.`].join(" "), { details: {
+			branchId: branch.id,
+			roleName: requested,
+			availableRoles: roles.map((r) => r.name)
+		} });
+		return requested;
+	}
+	if (roles.length === 0) throw new PlatformError(ErrorCode.BranchNotFound, [`fetchEnv: branch ${branch.name} (${branch.id}) has no roles.`, "Create one via the Neon console or pass `roleName` explicitly."].join(" "), { details: { branchId: branch.id } });
+	if (roles.length === 1) return roles[0].name;
+	const owner = roles.find((r) => r.name === NEON_DEFAULT_OWNER_ROLE);
+	if (owner) return owner.name;
+	const appRoles = roles.filter((r) => !NEON_MANAGED_AUTH_ROLES.has(r.name));
+	if (appRoles.length === 1) return appRoles[0].name;
+	throw new PlatformError(ErrorCode.AmbiguousBranchAuth, [`fetchEnv: branch ${branch.name} (${branch.id}) has ${roles.length} roles and none is "${NEON_DEFAULT_OWNER_ROLE}"; cannot auto-pick.`, `Pass \`roleName\` explicitly. Available: ${roles.map((r) => r.name).join(", ")}.`].join(" "), { details: {
+		branchId: branch.id,
+		availableRoles: roles.map((r) => r.name)
+	} });
+}
+function pickDatabaseName(databases, branch, requested) {
+	if (requested) {
+		if (!databases.some((d) => d.name === requested)) throw new PlatformError(ErrorCode.BranchNotFound, [`fetchEnv: database "${requested}" not found on branch ${branch.name} (${branch.id}).`, `Existing databases: ${databases.map((d) => d.name).join(", ") || "(none)"}.`].join(" "), { details: {
+			branchId: branch.id,
+			databaseName: requested,
+			availableDatabases: databases.map((d) => d.name)
+		} });
+		return requested;
+	}
+	if (databases.length === 0) throw new PlatformError(ErrorCode.BranchNotFound, [`fetchEnv: branch ${branch.name} (${branch.id}) has no databases.`, "Create one via the Neon console or pass `databaseName` explicitly."].join(" "), { details: { branchId: branch.id } });
+	const neondb = databases.find((d) => d.name === NEON_DEFAULT_DATABASE);
+	if (neondb) return neondb.name;
+	if (databases.length === 1) return databases[0].name;
+	throw new PlatformError(ErrorCode.AmbiguousBranchAuth, [`fetchEnv: branch ${branch.name} (${branch.id}) has ${databases.length} databases and none is named "${NEON_DEFAULT_DATABASE}"; cannot auto-pick.`, `Rename one to "${NEON_DEFAULT_DATABASE}" or keep a single database on the branch (or, when calling fetchEnv directly, pass \`databaseName\`). Available: ${databases.map((d) => d.name).join(", ")}.`].join(" "), { details: {
+		branchId: branch.id,
+		availableDatabases: databases.map((d) => d.name)
+	} });
+}
+/**
+* Project a fully-resolved {@link NeonEnv} into the OS-level `{ KEY: value }` pairs used
+* for cross-process transport. Named after the web-platform `.entries()` convention
+* (`URLSearchParams` / `Headers` / `FormData`); returns a `Record` rather than an
+* iterator of tuples since that's the shape env injection needs (wrap with
+* `Object.entries(...)` if you want literal `[key, value]` pairs). Used by `neon-env run`
+* to inject the vars into a subprocess's `process.env`.
+*
+* Walks the value at runtime so it works for any `NeonEnv<C>` regardless of which
+* conditional namespaces are present.
+*/
+function toEntries(env) {
+	const out = {};
+	const put = (key, value) => {
+		if (value !== void 0) out[key] = value;
+	};
+	const K = NEON_ENV_VAR_KEYS;
+	put(K.postgres.databaseUrl, env.postgres?.databaseUrl);
+	put(K.postgres.databaseUrlUnpooled, env.postgres?.databaseUrlUnpooled);
+	put(K.branch.name, env.branch?.name);
+	put(K.auth.baseUrl, env.auth?.baseUrl);
+	put(K.auth.jwksUrl, env.auth?.jwksUrl);
+	put(K.dataApi.url, env.dataApi?.url);
+	put(K.storage.accessKeyId, env.storage?.accessKeyId);
+	put(K.storage.secretAccessKey, env.storage?.secretAccessKey);
+	put(K.storage.endpoint, env.storage?.endpoint);
+	put(K.storage.region, env.storage?.region);
+	put(K.aiGateway.apiKey, env.aiGateway?.apiKey);
+	put(K.aiGateway.baseUrl, env.aiGateway?.baseUrl);
+	return out;
+}
+//#endregion
+//#region src/env_services.ts
+/**
+* The services `env pull --service` can select: every Neon service that produces branch env
+* vars. `functions` is the one left out — a function's env comes from the local `neon.ts`,
+* never from the branch, so there is nothing to pull.
+*/
+const ENV_PULL_SERVICES = NEON_SERVICES.filter((service) => service !== "functions");
+/** Why the services `env pull` leaves out are not selectable, for the refusal message. */
+const ENV_PULL_UNAVAILABLE = { functions: "a function's env comes from your neon.ts, not from the branch, so there is nothing to pull" };
+/** Every OS-level env var `env pull` can write, in stable emit order. */
+const ENV_PULL_KEYS = [
+	...Object.values(NEON_ENV_VAR_KEYS.postgres),
+	NEON_ENV_VAR_KEYS.branch.name,
+	...Object.values(NEON_ENV_VAR_KEYS.auth),
+	...Object.values(NEON_ENV_VAR_KEYS.dataApi),
+	...Object.values(NEON_ENV_VAR_KEYS.storage),
+	...Object.values(NEON_ENV_VAR_KEYS.aiGateway)
+];
+/** The OS-level env vars each service contributes to a pulled `.env`. */
+const SERVICE_ENV_KEYS = {
+	postgres: Object.values(NEON_ENV_VAR_KEYS.postgres),
+	auth: Object.values(NEON_ENV_VAR_KEYS.auth),
+	"data-api": Object.values(NEON_ENV_VAR_KEYS.dataApi),
+	"object-storage": Object.values(NEON_ENV_VAR_KEYS.storage),
+	"ai-gateway": Object.values(NEON_ENV_VAR_KEYS.aiGateway),
+	functions: []
+};
+/**
+* The subset of {@link SERVICE_ENV_KEYS} a pull *owns*, and so may prune from the target file
+* when the branch no longer has it. Object storage is deliberately absent: it is emitted under
+* the third-party `AWS_*` names, which collide with credentials a user may set by hand, so
+* `env pull` only ever writes them.
+*/
+const SERVICE_OWNED_ENV_KEYS = {
+	...SERVICE_ENV_KEYS,
+	"object-storage": []
+};
+/**
+* Branch identity. Not a service — every branch has a name — so a scoped pull refreshes it
+* alongside whatever services were selected.
+*/
+const BRANCH_ENV_KEY = NEON_ENV_VAR_KEYS.branch.name;
+/** The service that produces a key, or `null` for branch identity. */
+const ENV_KEY_SERVICE = {
+	DATABASE_URL: "postgres",
+	DATABASE_URL_UNPOOLED: "postgres",
+	NEON_BRANCH: null,
+	NEON_AUTH_BASE_URL: "auth",
+	NEON_AUTH_JWKS_URL: "auth",
+	NEON_DATA_API_URL: "data-api",
+	AWS_ACCESS_KEY_ID: "object-storage",
+	AWS_SECRET_ACCESS_KEY: "object-storage",
+	AWS_ENDPOINT_URL_S3: "object-storage",
+	AWS_REGION: "object-storage",
+	NEON_AI_GATEWAY_TOKEN: "ai-gateway",
+	NEON_AI_GATEWAY_BASE_URL: "ai-gateway"
+};
+const serviceForEnvKey = (key) => ENV_KEY_SERVICE[key];
+/** Services that must be resolved to produce the selected env keys. */
+const servicesForEnvKeys = (keys) => ENV_PULL_SERVICES.filter((service) => keys.some((key) => ENV_KEY_SERVICE[key] === service));
+/** Every env var the selected services contribute, plus branch identity. */
+const envServiceKeys = (services) => {
+	const keys = /* @__PURE__ */ new Set([BRANCH_ENV_KEY]);
+	for (const service of services) for (const key of SERVICE_ENV_KEYS[service]) keys.add(key);
+	return keys;
+};
+/**
+* The env vars a pull scoped to `services` may prune. Narrower than the unscoped set on
+* purpose: `env pull -s ai-gateway` says nothing about `DATABASE_URL`, so it must leave it
+* alone rather than treat its absence from this pull as "the branch no longer has it".
+*/
+const ownedEnvServiceKeys = (services) => services.flatMap((service) => SERVICE_OWNED_ENV_KEYS[service]);
+/**
+* The exact env vars an explicit selection writes. Services contribute their complete
+* bundles plus branch identity; `--env` contributes only the named keys. The two selectors
+* compose as a union.
+*/
+const envKeysForSelection = (services, envKeys) => {
+	const selected = services.length > 0 ? envServiceKeys(services) : /* @__PURE__ */ new Set();
+	for (const key of envKeys) selected.add(key);
+	if (selected.has(NEON_ENV_VAR_KEYS.storage.accessKeyId) !== selected.has(NEON_ENV_VAR_KEYS.storage.secretAccessKey)) throw new Error("AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY must be selected together: they are two halves of one newly issued object-storage credential. Add the missing key to --env, or use --service object-storage.");
+	return ENV_PULL_KEYS.filter((key) => selected.has(key));
+};
+/** Parse repeated or comma-separated `--env` values into canonical env-key order. */
+const parseEnvPullKeys = (raw, flag) => {
+	const names = raw.flatMap((value) => value.split(",")).map((name) => name.trim()).filter((name) => name !== "");
+	const supported = `Supported values: ${ENV_PULL_KEYS.join(", ")}.`;
+	if (names.length === 0) throw new Error(`${flag} needs at least one env variable. ${supported}`);
+	const unknown = names.filter((name) => !ENV_PULL_KEYS.some((key) => key === name));
+	if (unknown.length > 0) {
+		const displayNames = unknown.map(redactUnknownEnvValue);
+		const suggestions = [...new Set(unknown.map(suggestEnvPullKey).filter((key) => key !== null))];
+		const suggestion = suggestions.length > 0 ? ` Did you mean ${suggestions.join(" or ")}?` : "";
+		throw new Error(`Unknown env variable${unknown.length === 1 ? "" : "s"} ${displayNames.join(", ")}.${suggestion} ${supported}`);
+	}
+	return ENV_PULL_KEYS.filter((key) => names.includes(key));
+};
+const redactUnknownEnvValue = (value) => {
+	const separator = value.indexOf("=");
+	if (separator !== -1) {
+		const key = value.slice(0, separator);
+		return ENV_PULL_KEYS.some((supportedKey) => supportedKey === key) ? `${key}=<redacted>` : "<redacted invalid value>";
+	}
+	return "<redacted invalid value>";
+};
+const suggestEnvPullKey = (value) => {
+	if (value.includes("=")) return null;
+	const closest = ENV_PULL_KEYS.map((key) => [key, editDistance(value, key)]).sort((a, b) => a[1] - b[1])[0];
+	return closest && closest[1] <= 2 ? closest[0] : null;
+};
+const editDistance = (left, right) => {
+	let previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+	for (let leftIndex = 1; leftIndex <= left.length; leftIndex += 1) {
+		const current = [leftIndex];
+		for (let rightIndex = 1; rightIndex <= right.length; rightIndex += 1) current[rightIndex] = Math.min((previous[rightIndex] ?? 0) + 1, (current[rightIndex - 1] ?? 0) + 1, (previous[rightIndex - 1] ?? 0) + (left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1));
+		previous = current;
+	}
+	return previous[right.length] ?? right.length;
+};
+/** Narrow yargs' array option value without accepting any other runtime shape. */
+const envPullFlagValue = (value) => Array.isArray(value) ? value.map(String) : void 0;
+//#endregion
+export { policyEnvKeys as _, envKeysForSelection as a, toEntries as b, ownedEnvServiceKeys as c, servicesForEnvKeys as d, NEON_ENV_VAR_KEYS as f, fetchEnvKeys as g, credentialName as h, ENV_PULL_UNAVAILABLE as i, parseEnvPullKeys as l, credentialEnvKeys as m, ENV_PULL_KEYS as n, envPullFlagValue as o, createApiFromOptions as p, ENV_PULL_SERVICES as r, envServiceKeys as s, BRANCH_ENV_KEY as t, serviceForEnvKey as u, previewCredentialScopes as v, resolveBranchPolicy as y };

package/dist/_chunks/paths-DMq0Lt7a.js

@@ -0,0 +1,151 @@
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+//#region ../../internals/cli-core/dist/paths.js
+/**
+* # Where the Neon CLIs keep their files on disk
+*
+**Deliberately impure.** It reads environment variables and touches the filesystem, which
+* `@neon/config` — the package this used to be a subpath of — must never do from its root
+* export. It lives here instead of there precisely so that a policy-facing package does not
+* carry implementor-only code.
+*
+* It exists because three separate readers each grew their own answer to "where is the
+* config directory", and all three disagreed: `packages/cli` honoured `XDG_CONFIG_HOME` but
+* not `NEONCTL_CONFIG_DIR`, `packages/env` honoured the env var but not XDG, and the init
+* flow hardcoded `~/.config/neonctl`. With `XDG_CONFIG_HOME` set, the CLI wrote
+* credentials somewhere the other two never looked.
+*
+* ## The directory
+*
+* `neon` is the current name; `neonctl` is the legacy one, kept readable forever. Resolution,
+* each entry winning over the next:
+*
+* 1. An explicit directory (a `--config-dir` flag) — **exact**, no legacy fallback.
+* 2. `NEON_CONFIG_DIR` — exact.
+* 3. `NEONCTL_CONFIG_DIR` (legacy name) — exact.
+* 4. `$XDG_CONFIG_HOME/neon`, else `<home>/.config/neon`.
+*
+* An explicitly chosen directory is never paired with a fallback: `--config-dir /tmp/ci` that
+* quietly read `~/.config/neonctl` would defeat the point of passing it.
+*
+* ## The files
+*
+* {@link resolveConfigFile} answers "which path should I use for this file", and it is the
+* same answer for reading and writing:
+*
+* - Present in `neon/` → use it.
+* - Present only in `neonctl/` → **use it there, in place.** An existing credentials file is
+*   never copied or moved, so nothing is left behind to go stale and no other tool starts
+*   reading an abandoned token.
+* - Present in neither → the new location. New files only ever appear under `neon/`.
+*/
+/** Current directory name. New files are created here. */
+const CONFIG_DIR_NAME = "neon";
+/** Legacy directory name, read forever so existing installs keep working untouched. */
+const LEGACY_CONFIG_DIR_NAME = "neonctl";
+/** Where files are created. See the module docs for the precedence. */
+function configDir(options = {}) {
+	const explicit = explicitDir(options);
+	if (explicit) return explicit;
+	return join(configHome(options.env ?? process.env), CONFIG_DIR_NAME);
+}
+/**
+* The legacy directory, or `undefined` when the location was chosen explicitly (in which
+* case there is no legacy counterpart to fall back to).
+*/
+function legacyConfigDir(options = {}) {
+	if (explicitDir(options)) return void 0;
+	return join(configHome(options.env ?? process.env), LEGACY_CONFIG_DIR_NAME);
+}
+/**
+* Resolve one file inside the config directory. Prefers the current location, falls back to
+* an existing legacy file **in place**, and otherwise points at the current location so new
+* files are created there.
+*/
+function resolveConfigFile(fileName, options = {}) {
+	const dir = configDir(options);
+	const current = resolve(dir, fileName);
+	if (existsSync(current)) return {
+		path: current,
+		dir,
+		isLegacy: false,
+		exists: true
+	};
+	const legacyDir = legacyConfigDir(options);
+	if (legacyDir) {
+		const legacy = resolve(legacyDir, fileName);
+		if (existsSync(legacy)) return {
+			path: legacy,
+			dir: legacyDir,
+			isLegacy: true,
+			exists: true
+		};
+	}
+	return {
+		path: current,
+		dir,
+		isLegacy: false,
+		exists: false
+	};
+}
+/** `$XDG_CONFIG_HOME`, else `<home>/.config`. Falls back to a relative `.config` with no home. */
+function configHome(env) {
+	const xdg = nonEmpty(env.XDG_CONFIG_HOME);
+	if (xdg) return xdg;
+	const home = nonEmpty(env.HOME) ?? nonEmpty(env.USERPROFILE);
+	return home ? join(home, ".config") : ".config";
+}
+function explicitDir(options) {
+	const env = options.env ?? process.env;
+	return nonEmpty(options.dir) ?? nonEmpty(env.NEON_CONFIG_DIR) ?? nonEmpty(env.NEONCTL_CONFIG_DIR);
+}
+function nonEmpty(value) {
+	if (typeof value !== "string") return void 0;
+	const trimmed = value.trim();
+	return trimmed === "" ? void 0 : trimmed;
+}
+const CREDENTIALS_FILE = "credentials.json";
+/**
+* Default for `--config-dir`: `$XDG_CONFIG_HOME/neon`, else `~/.config/neon`.
+*
+* The directory was called `neonctl` until the CLI was renamed. An existing one is still read —
+* see {@link credentialsPath} — but it is never written to, moved, or deleted.
+*/
+const defaultDir = configDir();
+/**
+* Where this invocation's `credentials.json` lives.
+*
+* When `--config-dir` was left at its default, an existing file in the legacy `neonctl`
+* directory is used **in place**: an install that predates the rename keeps working, and its
+* credentials are never duplicated into a second location where one copy could go stale while
+* another tool still reads it.
+*
+* A `--config-dir` the user actually passed is used exactly as given. Falling back out of an
+* explicitly chosen directory would defeat the reason for choosing it — a CI run pointed at a
+* scratch directory must never pick up a developer's real credentials.
+*/
+const credentialsPath = (dir) => resolveConfigFile(CREDENTIALS_FILE, dir === defaultDir ? {} : { dir }).path;
+/**
+* Whether a credentials file is one the CLI created, rather than a path a profile adopted.
+*
+* Anything that deletes a credential has to ask this first. A profile entry may point anywhere —
+* that is what makes adopting an existing directory a one-line edit — and a file we did not
+* create is not ours to remove.
+*/
+const isInsideConfigDir = (configDirectory, file) => `${resolve(file)}/`.startsWith(`${resolve(configDirectory)}/`);
+/**
+* Whether a credentials file is one the CLI owns, counting the legacy `neonctl` directory.
+*
+* {@link credentialsPath} deliberately reads an existing legacy file in place rather than
+* migrating it, so for a default config directory that file is ours even though it sits outside
+* `neon/`. Judging ownership on the current directory alone would call an install that predates
+* the rename "adopted".
+*/
+const isOwnedCredentialPath = (configDirectory, file) => {
+	if (isInsideConfigDir(configDirectory, file)) return true;
+	if (configDirectory !== defaultDir) return false;
+	const legacy = legacyConfigDir();
+	return legacy !== void 0 && isInsideConfigDir(legacy, file);
+};
+//#endregion
+export { isOwnedCredentialPath as a, isInsideConfigDir as i, credentialsPath as n, resolveConfigFile as o, defaultDir as r, CREDENTIALS_FILE as t };