neon 3.0.0 → 3.1.1

package/dist/_chunks/env-NbA61JR3.js

@@ -0,0 +1,585 @@
+import { log } from "../log.js";
+import { getCliName } from "../utils/cli_name.js";
+import { _ as policyEnvKeys, a as envKeysForSelection, b as toEntries, d as servicesForEnvKeys, f as NEON_ENV_VAR_KEYS, g as fetchEnvKeys, h as credentialName, m as credentialEnvKeys, p as createApiFromOptions, r as ENV_PULL_SERVICES, u as serviceForEnvKey, v as previewCredentialScopes, y as resolveBranchPolicy } from "./env_services-Tz9G4JeT.js";
+import { formatInstallCommand, resolvePackageManager } from "../utils/package_manager.js";
+import { credentialScopesSatisfied } from "@neon/config/v1";
+import { ErrorCode as ErrorCode$1, createNeonApiFromOptions as createNeonApiFromOptions$1, isPlatformError, loadConfigFromFile } from "@neon/config";
+import { plan, pullConfig } from "@neon/config-runtime";
+//#region ../../internals/env-core/dist/reuse-secrets.js
+/**
+* Resolve a branch's env while keeping one-time secrets the caller already holds.
+*
+* {@link fetchEnvKeys} — and the public `fetchEnv` — only ever *fetch*. The Neon API returns a
+* credential's `api_token` / `s3_secret_access_key` exactly once, at mint time, so "fetching"
+* them means minting a new credential; a plain `fetchEnv` on every `neon dev` start or `env
+* pull` would leave a live credential behind each time. This is the wrapper that avoids that:
+* it looks at what the caller already has, decides what is still usable, and asks `fetchEnv`
+* for only the rest.
+*
+* The check is a real verification, not a presence test. A persisted secret is kept only when
+* it names a credential that still exists on this branch, is not revoked or expired, and
+* carries every scope the policy needs. A `.env.example` placeholder, a credential revoked in
+* the console, one copied in from another branch, or one predating a newly-enabled feature all
+* fail that check and get replaced.
+*
+* None of this needs local bookkeeping, because the secrets carry their own credential id:
+* `AWS_ACCESS_KEY_ID` **is** the credential's `tokenId` (the storage gateway authenticates
+* against the full id), and the AI Gateway token is minted as `nt_live_<tokenIdShort>_<secret>`,
+* where `tokenIdShort` is what the credentials list reports. The env source being replaced is
+* the record of what the last call issued.
+*
+* ```ts
+* import { fetchEnvReusingSecrets } from "@neon-internals/env-core/reuse-secrets";
+*
+* const { vars, credential } = await fetchEnvReusingSecrets(config, {
+*     projectId,
+*     branch: "main",
+*     env: { ...process.env, ...readEnvFile(".env") },
+* });
+* if (credential.issued) console.log(`new values for ${credential.keys.join(", ")}`);
+* ```
+*/
+async function fetchEnvReusingSecrets(config, options) {
+	const { env: source = process.env, keys: requestedKeys, revokeSuperseded = true, ...fetchOptions } = options;
+	const api = options.api ?? createApiFromOptions(options);
+	const { branch, desired } = await resolveBranchPolicy(config, options, api);
+	const allPolicyKeys = policyEnvKeys(desired);
+	const requested = requestedKeys ? new Set(requestedKeys) : null;
+	const selectedPolicyKeys = requested === null ? allPolicyKeys : allPolicyKeys.filter((key) => requested.has(key));
+	const selected = new Set(selectedPolicyKeys);
+	const K = NEON_ENV_VAR_KEYS;
+	const storageCredentialSelected = (desired.preview?.buckets.length ?? 0) > 0 && (selected.has(K.storage.accessKeyId) || selected.has(K.storage.secretAccessKey));
+	const gatewayCredentialSelected = (desired.preview?.aiGatewayEnabled ?? false) && selected.has(K.aiGateway.apiKey);
+	const secretKeys = credentialEnvKeys({
+		storage: storageCredentialSelected,
+		aiGateway: gatewayCredentialSelected
+	}).filter((key) => selected.has(key));
+	if (secretKeys.length === 0) {
+		const fetched = await fetchEnvKeys(config, fetchOptions, requested === null ? null : selectedPolicyKeys);
+		return {
+			vars: preferPersisted(toEntries(fetched), source),
+			credential: {
+				issued: false,
+				keys: [],
+				revoked: [],
+				superseded: []
+			}
+		};
+	}
+	const persisted = readPersistedSecrets(source);
+	const storageCredentialManaged = requested === null || storageCredentialSelected;
+	const gatewayCredentialManaged = requested === null || gatewayCredentialSelected;
+	const complete = (!storageCredentialSelected || Boolean(persisted.accessKeyId && persisted.secretAccessKey)) && (!gatewayCredentialSelected || Boolean(persisted.apiToken));
+	const named = storageCredentialManaged && persisted.accessKeyId !== "" || gatewayCredentialManaged && persisted.apiToken !== "" ? namedCredentials(await api.listCredentials(options.projectId, branch.id), persisted) : {
+		storage: null,
+		gateway: null
+	};
+	const reusable = complete ? reusableCredential(named, {
+		storageEnabled: storageCredentialSelected,
+		gatewayEnabled: gatewayCredentialSelected
+	}) : null;
+	const scopes = previewCredentialScopes(desired.preview, {
+		storage: storageCredentialSelected,
+		aiGateway: gatewayCredentialSelected
+	});
+	const keep = reusable !== null && credentialScopesSatisfied(reusable.scopes, scopes);
+	const fetchKeys = keep ? selectedPolicyKeys.filter((key) => !secretKeys.includes(key)) : selectedPolicyKeys;
+	const fetched = await fetchEnvKeys(config, {
+		...fetchOptions,
+		branchId: branch.id,
+		api
+	}, fetchKeys);
+	const vars = preferPersisted(toEntries(fetched), source);
+	if (keep) {
+		for (const key of secretKeys) {
+			const value = source[key];
+			if (value !== void 0) vars[key] = value;
+		}
+		return {
+			vars,
+			credential: {
+				issued: false,
+				keys: secretKeys,
+				revoked: [],
+				superseded: []
+			}
+		};
+	}
+	const ours = /* @__PURE__ */ new Set();
+	for (const meta of [storageCredentialManaged ? named.storage : null, gatewayCredentialManaged ? named.gateway : null]) if (meta !== null && meta.principalType === "user" && meta.name === credentialName(branch.name)) ours.add(meta.tokenId);
+	if (revokeSuperseded) for (const tokenId of ours) await api.revokeCredential(options.projectId, branch.id, tokenId);
+	return {
+		vars,
+		credential: {
+			issued: true,
+			keys: secretKeys,
+			revoked: revokeSuperseded ? [...ours] : [],
+			superseded: revokeSuperseded ? [] : [...ours]
+		}
+	};
+}
+/** Read the branch credential's secrets out of an env source. */
+function readPersistedSecrets(source) {
+	const storage = NEON_ENV_VAR_KEYS.storage;
+	const gateway = NEON_ENV_VAR_KEYS.aiGateway;
+	return {
+		accessKeyId: source[storage.accessKeyId] ?? "",
+		secretAccessKey: source[storage.secretAccessKey] ?? "",
+		apiToken: source[gateway.apiKey] ?? ""
+	};
+}
+/**
+* Keep a persisted value rather than overwriting it with an empty fetched one.
+*
+* Neon Auth's `base_url` is the case that needs this: integrations created before the API
+* returned it answer with an empty string, and the persisted copy is the only one left. An
+* empty fetched value never carries more information than a non-empty persisted one, so
+* preferring the latter is safe for every var — and it keeps a pull from blanking a working
+* line in someone's `.env`.
+*/
+function preferPersisted(vars, source) {
+	const out = { ...vars };
+	for (const [key, value] of Object.entries(out)) {
+		if (value !== "") continue;
+		const persisted = source[key];
+		if (persisted !== void 0 && persisted !== "") out[key] = persisted;
+	}
+	return out;
+}
+/**
+* The credential id embedded in an AI Gateway token. The API mints them as
+* `nt_live_<tokenIdShort>_<secret>`, and `tokenIdShort` is the public identifier the credentials
+* list reports — so a persisted token names the credential that issued it. Returns `null` for
+* anything not in that shape (a `.env.example` placeholder, a hand-typed value), which callers
+* treat as unverifiable.
+*/
+function gatewayTokenIdShort(apiToken) {
+	return /^nt_live_([^_]+)_.+$/.exec(apiToken)?.[1] ?? null;
+}
+/** Whether an issued credential can still be used: not revoked, not past its expiry. */
+function isLiveCredential(meta, now) {
+	if (meta.revokedAt !== void 0) return false;
+	if (meta.expiresAt === void 0) return true;
+	const expiresAt = Date.parse(meta.expiresAt);
+	return Number.isNaN(expiresAt) || expiresAt > now;
+}
+/**
+* The live credentials the persisted secrets name — at most one per half. A half that names
+* nothing contributes nothing, which is what a placeholder, a credential revoked in the
+* console, and one copied in from another branch all look like from here.
+*/
+function namedCredentials(live, persisted) {
+	const usable = live.filter((meta) => isLiveCredential(meta, Date.now()));
+	const shortId = persisted.apiToken ? gatewayTokenIdShort(persisted.apiToken) : null;
+	return {
+		storage: persisted.accessKeyId ? usable.find((meta) => meta.tokenId === persisted.accessKeyId) ?? null : null,
+		gateway: shortId ? usable.find((meta) => meta.tokenIdShort === shortId) ?? null : null
+	};
+}
+/**
+* The credential the persisted secrets can be *reused* as, or `null`.
+*
+* Strict on purpose: every half the policy enables has to name a live credential, and when both
+* features are enabled they must name the *same* one — they share a single credential, so
+* halves that disagree came from two different calls and neither can be trusted.
+*/
+function reusableCredential(named, enabled) {
+	if (enabled.storageEnabled && enabled.gatewayEnabled) return named.storage && named.gateway && named.storage.tokenId === named.gateway.tokenId ? named.storage : null;
+	if (enabled.storageEnabled) return named.storage;
+	if (enabled.gatewayEnabled) return named.gateway;
+	return null;
+}
+//#endregion
+//#region src/dev/env.ts
+/** The API-targeting options every runtime call forwards from the context. */
+const apiOptions = (ctx) => ({
+	...ctx.apiKey ? { apiKey: ctx.apiKey } : {},
+	...ctx.apiHost ? { apiHost: ctx.apiHost } : {},
+	...ctx.api ? { api: ctx.api } : {}
+});
+/**
+* Thrown when a `neon.ts` policy declares a branch-level resource (Neon Auth,
+* Data API, a bucket, the AI Gateway) that the linked remote branch does not
+* have yet. Unlike every other failure in {@link resolveDevEnv} — which degrades
+* to "run without injection" — this is a hard stop: the user's intent (a policy)
+* cannot be honored, and silently dropping the secret would be more confusing
+* than refusing to start. The fix is to provision the resource first.
+*/
+var DevEnvMismatchError = class extends Error {
+	constructor(..._args) {
+		super(..._args);
+		this.name = "DevEnvMismatchError";
+	}
+};
+/**
+* Signals that no project/branch context could be resolved, so there is nothing to
+* resolve env from. `resolveDevEnv` degrades on this (dev runs without injection);
+* `env pull` surfaces it (an explicit pull needs a branch).
+*/
+var MissingBranchContextError = class extends Error {
+	constructor(..._args2) {
+		super(..._args2);
+		this.name = "MissingBranchContextError";
+	}
+};
+/**
+* Thrown when an explicit `--service` / `--env` selection needs a service the branch lacks.
+* Unlike the policy path — where the same situation is a {@link DevEnvMismatchError} pointing
+* at `deploy` — the user named the service on the command line, so the fix is to provision it
+* or drop it from the selection.
+*/
+var ServiceNotOnBranchError = class extends Error {
+	constructor(..._args3) {
+		super(..._args3);
+		this.name = "ServiceNotOnBranchError";
+	}
+};
+/**
+* Resolve the branch's Neon env vars (pooled / direct `DATABASE_URL`, plus Auth /
+* Data API when enabled) into a `{ KEY: value }` map. Shared by `neon dev` (which
+* injects them) and `neon env pull` (which writes them to a `.env` file).
+*
+* Tiered:
+*
+*   0. {@link DevEnvContext.services} or {@link DevEnvContext.envKeys} is set -> that
+*      selection *is* the policy, and any `neon.ts` is ignored. See
+*      {@link resolveSelectedServices}.
+*   1. a `neon.ts` policy is found -> the policy is the source of truth. We first
+*      check it against the branch's live state (`plan`); if it declares a resource
+*      the branch is missing, we stop with a {@link DevEnvMismatchError} pointing at
+*      `neonctl deploy`. Otherwise `fetchEnv` evaluates the policy.
+*   2. no `neon.ts`, but a project + branch are known -> `pullConfig` reads the
+*      branch's live state (Auth / Data API enablement plus any object-storage
+*      buckets) into a config, then `fetchEnv` resolves what is actually enabled —
+*      so a branch with a bucket gets its `AWS_*` storage vars pulled with no policy.
+*      With {@link DevEnvContext.implyAiGateway}, the AI Gateway is added on top, since
+*      `pullConfig` cannot read it back.
+*   3. otherwise -> throw {@link MissingBranchContextError}.
+*
+* Unlike {@link resolveDevEnv}, this never swallows errors — callers decide how to
+* handle them.
+*/
+const resolveNeonEnvVars = async (ctx) => {
+	if (ctx.services !== void 0 || ctx.envKeys !== void 0) return await resolveSelectedServices(ctx, ctx.services ?? [], ctx.envKeys ?? []);
+	const config = await loadNeonConfig(ctx.cwd);
+	if (config) {
+		if (!ctx.projectId || !ctx.branchId) throw new MissingBranchContextError(`Found a neon.ts but could not resolve the project/branch. Run \`${getCliName()} link\` and \`${getCliName()} checkout <branch>\`, or pass --project-id / --branch.`);
+		const envConfig = withoutPreviewFunctions(config);
+		await assertPolicyMatchesBranch(envConfig, ctx);
+		return await fetchAndProject(envConfig, ctx);
+	}
+	if (ctx.projectId && ctx.branchId) {
+		const pulled = await pullConfig({
+			projectId: ctx.projectId,
+			branchId: ctx.branchId,
+			...apiOptions(ctx)
+		});
+		if (!ctx.implyAiGateway) return await fetchAndProject(pulled.config, ctx);
+		return await resolveWithImpliedGateway(pulled.config, ctx, {
+			projectId: ctx.projectId,
+			branchId: ctx.branchId
+		});
+	}
+	throw new MissingBranchContextError(`No project/branch context found. Link a branch (\`${getCliName()} link\` / \`${getCliName()} checkout\`) or pass --project-id and --branch.`);
+};
+/** The same config with the AI Gateway enabled, leaving any other `preview` entries intact. */
+const withAiGateway = (config) => ({
+	...config,
+	preview: {
+		...config.preview,
+		aiGateway: true
+	}
+});
+/**
+* Tier-2 resolution with the AI Gateway added on top of the branch's read-back state.
+*
+* The gateway is not detectable — `pullConfig` reports no enabled flag for it — so it is
+* implied rather than observed. Nobody named it, so it must never be the reason the whole
+* resolve fails: a project outside the regions where branch credentials exist would otherwise
+* lose its `DATABASE_URL` too, and `neon dev` would start with no env at all.
+*
+* So the gateway is only added once its credential endpoint has been shown to answer, by
+* reading the branch's credentials first. A project that does not have them says so on a
+* read, before anything is minted — which is the whole question, since the gateway's env is a
+* credential and nothing else.
+*
+* Deciding this **before** resolving, rather than by catching and retrying, is what keeps it
+* honest. A retry re-runs every call the first attempt made, so it would blame the gateway for
+* a one-off failure in shared work, and — worse — a first attempt that minted a credential and
+* then failed would be papered over by a second that succeeds without one, swallowing the
+* error and stranding a secret nobody holds. Once the read succeeds, a later failure is a real
+* failure and propagates: the same thing already happens on a branch with object storage,
+* whose credential is minted whether or not the gateway is involved.
+*/
+const resolveWithImpliedGateway = async (config, ctx, branch) => {
+	const unreachable = await credentialsUnreachable(ctx, branch);
+	if (unreachable === null) return await fetchAndProject(withAiGateway(config), ctx);
+	log.warning(`Could not reach the AI Gateway's credentials, so %s were not resolved. Everything else was. Either this project does not have the AI Gateway, or the call failed — \`${getCliName()} env pull -s ai-gateway\` will say which.\nDetails: %s`, [NEON_ENV_VAR_KEYS.aiGateway.apiKey, NEON_ENV_VAR_KEYS.aiGateway.baseUrl].join(" and "), unreachable);
+	return {
+		...await fetchAndProject(config, ctx),
+		skipped: ["ai-gateway"]
+	};
+};
+/**
+* Why the branch's credentials could not be read, or `null` when they could. A plain read: it
+* mints nothing, revokes nothing, and changes nothing, so asking is free of the side effects
+* that make a failed resolve ambiguous.
+*/
+const credentialsUnreachable = async (ctx, branch) => {
+	try {
+		await apiFor(ctx).listCredentials(branch.projectId, branch.branchId);
+		return null;
+	} catch (err) {
+		return err instanceof Error ? err.message : String(err);
+	}
+};
+/** The adapter for direct branch reads: the injected one in tests, else built from options. */
+const apiFor = (ctx) => ctx.api ?? createNeonApiFromOptions$1("neon env", {
+	...ctx.apiKey ? { apiKey: ctx.apiKey } : {},
+	...ctx.apiHost ? { apiHost: ctx.apiHost } : {}
+});
+/**
+* Tier-0: resolve exactly what `--service` / `--env` selected, with `neon.ts` ignored.
+*
+* The selection is checked against live project and branch state so a service that is named
+* but not provisioned fails by name, instead of quietly contributing dead vars. `postgres`
+* needs no check because every branch has it.
+*/
+const resolveSelectedServices = async (ctx, directServices, envKeys) => {
+	const { projectId, branchId } = ctx;
+	if (!projectId || !branchId) throw new MissingBranchContextError(`An explicit env selection needs a project and branch to read from. Run \`${getCliName()} link\` and \`${getCliName()} checkout <branch>\`, or pass --project-id / --branch.`);
+	const impliedServices = servicesForEnvKeys(envKeys);
+	const services = ENV_PULL_SERVICES.filter((service) => directServices.includes(service) || impliedServices.includes(service));
+	const selectedKeys = envKeysForSelection(directServices, envKeys);
+	const api = apiFor(ctx);
+	const has = (service) => services.includes(service);
+	const checkAiGateway = has("ai-gateway") && !selectedKeys.includes(NEON_ENV_VAR_KEYS.aiGateway.apiKey);
+	const [auth, dataApiEnabled, buckets, aiGatewayAvailable] = await Promise.all([
+		has("auth") ? api.getNeonAuth(projectId, branchId) : null,
+		has("data-api") ? readDataApiEnabled(api, projectId, branchId) : null,
+		has("object-storage") ? api.listBranchBuckets(projectId, branchId) : null,
+		checkAiGateway ? readAiGatewayAvailable(api, projectId, branchId) : null
+	]);
+	const config = configForServices(services, branchId, {
+		authEnabled: auth !== null,
+		dataApiEnabled,
+		buckets: buckets ?? [],
+		aiGatewayAvailable: aiGatewayAvailable ?? true
+	}, {
+		directServices,
+		envKeys
+	});
+	return await fetchAndProject(config, ctx, {
+		keys: selectedKeys,
+		revokeSuperseded: false
+	});
+};
+/**
+* Whether the branch has a Data API integration — or `null` when that cannot be determined.
+*
+* It is enabled per branch *and database*, so this has to probe the database `fetchEnv` will
+* resolve the URL from, or the two would disagree. That is Neon's default `neondb`, else the
+* only database; several databases with no `neondb` is a case `fetchEnv` refuses to auto-pick
+* at all. Reporting "no Data API integration" there would be a claim this read cannot support,
+* so it answers `null` and lets `fetchEnv` raise its own ambiguity error, which names the
+* databases and the fix.
+*/
+const readDataApiEnabled = async (api, projectId, branchId) => {
+	const databases = await api.listBranchDatabases(projectId, branchId);
+	const database = databases.find((db) => db.name === NEON_DEFAULT_DATABASE) ?? (databases.length === 1 ? databases[0] : void 0);
+	if (!database) return databases.length === 0 ? false : null;
+	return await api.getNeonDataApi(projectId, branchId, database.name) !== null;
+};
+const readAiGatewayAvailable = async (api, projectId, branchId) => {
+	try {
+		await api.listCredentials(projectId, branchId);
+		return true;
+	} catch (error) {
+		if (isPlatformError(error) && error.code === ErrorCode$1.FeatureUnavailable && (error.details.status === 404 || error.details.status === 501)) return false;
+		throw error;
+	}
+};
+/** Neon's default database, and the one `fetchEnv` prefers when a branch has several. */
+const NEON_DEFAULT_DATABASE = "neondb";
+/**
+* Build the `Config` an explicit `--service` / `--env` selection stands for, raising
+* {@link ServiceNotOnBranchError} for anything the branch does not have. Naming a service
+* that isn't there has to fail rather than contribute no vars, or a scoped pull would report
+* "no Neon env variables to pull" — which reads as a statement about the branch rather than
+* about the selection.
+*/
+const configForServices = (services, branchId, branch, selection) => {
+	const provisionWith = {
+		auth: `${getCliName()} neon-auth enable`,
+		"data-api": `${getCliName()} data-api create`,
+		"object-storage": `${getCliName()} buckets create <name>`
+	};
+	const notOnBranch = (service, what) => {
+		if (!selection.directServices.includes(service)) {
+			const names = selection.envKeys.filter((key) => serviceForEnvKey(key) === service).join(", ");
+			throw new ServiceNotOnBranchError(`--env ${names}: branch ${branchId} has no ${what}, so ${names} cannot be pulled. Provision it first (\`${provisionWith[service]}\`, or in the Neon Console), or drop ${names} from --env.`);
+		}
+		throw new ServiceNotOnBranchError(`--service ${service}: branch ${branchId} has no ${what}, so there are no ${service} env vars to pull. Provision it first (\`${provisionWith[service]}\`, or in the Neon Console), or drop ${service} from --service.`);
+	};
+	const aiGatewayUnavailable = () => {
+		const reason = "AI Gateway is not available for this Neon project because branch credentials are unavailable";
+		if (selection.directServices.includes("ai-gateway")) throw new ServiceNotOnBranchError(`--service ai-gateway: ${reason}. Use another project, or drop ai-gateway from --service.`);
+		const names = selection.envKeys.filter((key) => serviceForEnvKey(key) === "ai-gateway").join(", ");
+		throw new ServiceNotOnBranchError(`--env ${names}: ${reason}, so ${names} cannot be pulled. Use another project, or drop ${names} from --env.`);
+	};
+	const config = {};
+	if (services.includes("auth")) {
+		if (!branch.authEnabled) notOnBranch("auth", "Neon Auth integration");
+		config.auth = true;
+	}
+	if (services.includes("data-api")) {
+		if (branch.dataApiEnabled === false) notOnBranch("data-api", "Data API integration");
+		config.dataApi = true;
+	}
+	const preview = {};
+	if (services.includes("object-storage")) {
+		if (branch.buckets.length === 0) notOnBranch("object-storage", "object-storage buckets");
+		preview.buckets = Object.fromEntries(branch.buckets.map((bucket) => [bucket.name, { access: bucket.accessLevel }]));
+	}
+	if (services.includes("ai-gateway")) {
+		if (!branch.aiGatewayAvailable) aiGatewayUnavailable();
+		preview.aiGateway = true;
+	}
+	if (Object.keys(preview).length > 0) config.preview = preview;
+	return config;
+};
+/**
+* `neon dev`'s env resolver: {@link resolveNeonEnvVars} with graceful degradation.
+*
+* - Success → `{ vars }` (possibly just the always-present Postgres URLs).
+* - No linked branch / project → `{ vars: {}, skipped }` with a "link a branch" hint; the
+*   function still runs locally, just without Neon env.
+* - Any other failure (offline, transient API error) → `{ vars: {}, skipped }` naming the
+*   cause; again non-fatal.
+* - {@link DevEnvMismatchError} (policy declares a secret-bearing service the branch lacks)
+*   is the one hard stop and is re-thrown for the caller to surface.
+*/
+const resolveDevEnv = async (ctx) => {
+	try {
+		const { vars, credential } = await resolveNeonEnvVars(ctx);
+		return {
+			vars,
+			credential
+		};
+	} catch (err) {
+		if (err instanceof DevEnvMismatchError) throw err;
+		if (err instanceof MissingBranchContextError) {
+			log.debug("dev: %s; skipping env injection", err.message);
+			return {
+				vars: {},
+				skipped: { reason: `no linked Neon branch — run \`${getCliName()} link\`, then \`${getCliName()} checkout <branch>\`, to inject DATABASE_URL and friends` }
+			};
+		}
+		const detail = err instanceof Error ? err.message : String(err);
+		log.debug("dev: env resolution failed: %s", detail);
+		return {
+			vars: {},
+			skipped: { reason: `could not reach Neon (${detail}); running without Neon env` }
+		};
+	}
+};
+/**
+* Return the policy with its `preview.functions` removed, so the env path never enumerates
+* functions against the Neon API. Functions are local-source-bundled and produce no
+* branch-level secrets, so they are irrelevant to env resolution; probing them only risks
+* failing the whole resolve (undeployed function, or Functions Preview disabled on the
+* project). Buckets / AI Gateway and the top-level Auth / Data API toggles are preserved —
+* they DO carry env, so they must still be checked and resolved. Returns the config
+* unchanged when it declares no functions.
+*/
+const withoutPreviewFunctions = (config) => {
+	const preview = config.preview;
+	if (!preview?.functions) return config;
+	const previewWithoutFunctions = { ...preview };
+	delete previewWithoutFunctions.functions;
+	return {
+		...config,
+		preview: previewWithoutFunctions
+	};
+};
+/**
+* Tier-1 guard. Dry-run the policy against the branch's live state and stop if
+* it declares a branch-level resource the branch is missing. Built on `plan` so
+* it covers every present and future provisionable resource for free: any
+* `create` action is a resource `neonctl deploy` would provision.
+*
+* Called with functions already stripped (see {@link withoutPreviewFunctions}), so the
+* `plan` probe never enumerates the functions API — an undeployed function, or a project
+* without the Functions Preview, must never block local dev or sink env injection.
+*/
+const assertPolicyMatchesBranch = async (config, ctx) => {
+	const missing = (await plan(config, {
+		projectId: ctx.projectId,
+		branchId: ctx.branchId,
+		...apiOptions(ctx)
+	})).applied.filter(isMissingResource);
+	if (missing.length === 0) return;
+	throw new DevEnvMismatchError(`Your neon.ts declares ${missing.map((change) => change.identifier).join(", ")} for branch ${ctx.branchId}, but the branch does not have it yet, so the matching env vars cannot be injected. Provision it first with \`${getCliName()} deploy\` (or \`${getCliName()} config apply\`), then re-run \`${getCliName()} dev\`.`);
+};
+/**
+* A planned change that provisions a branch-level resource the branch lacks: a
+* `create` on a service (Neon Auth, Data API, a bucket, the AI Gateway). Branch
+* setting drift (`update`) and `noop`s are ignored — they don't block local dev
+* — and functions are excluded (see {@link assertPolicyMatchesBranch}).
+*/
+const isMissingResource = (change) => change.kind === "service" && change.action === "create" && !change.identifier.startsWith("function:");
+const fetchAndProject = async (config, ctx, opts = {}) => fetchEnvReusingSecrets(config, {
+	projectId: ctx.projectId,
+	branch: ctx.branchId,
+	...apiOptions(ctx),
+	...ctx.env ? { env: ctx.env } : {},
+	...opts.keys ? { keys: opts.keys } : {},
+	...opts.revokeSuperseded === false ? { revokeSuperseded: false } : {}
+});
+/**
+* Load a `neon.ts` policy if one exists on the path from `cwd` up to the repo
+* root. Returns `null` when there is none (the common "no config" case), and
+* surfaces real load errors (e.g. a syntax error in an existing file).
+*/
+/**
+* Substrings that mark a module-resolution failure while loading `neon.ts` —
+* almost always because the project's dependencies aren't installed yet (the
+* config imports `@neon/config` & friends). Deliberately specific:
+* the generic "…or a missing dependency…" hint the loader always appends is
+* NOT in here, so a real syntax/runtime error doesn't get mislabeled.
+*/
+const MISSING_DEPENDENCY_HINTS = [
+	"cannot find module",
+	"cannot find package",
+	"err_module_not_found",
+	"failed to resolve",
+	"could not resolve",
+	"module not found"
+];
+/** Flatten an error and its `cause` chain to one lowercased string for matching. */
+const errorChainText = (err) => {
+	const parts = [];
+	let current = err;
+	for (let depth = 0; current instanceof Error && depth < 6; depth++) {
+		parts.push(current.message);
+		current = current.cause;
+	}
+	return parts.join("\n").toLowerCase();
+};
+const looksLikeMissingDependency = (err) => {
+	const text = errorChainText(err);
+	return MISSING_DEPENDENCY_HINTS.some((hint) => text.includes(hint));
+};
+const loadNeonConfig = async (cwd) => {
+	try {
+		const { config } = await loadConfigFromFile({ cwd });
+		return config;
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		if (/Could not find a Neon config file/i.test(message)) return null;
+		if (looksLikeMissingDependency(err)) throw new Error(`Could not load neon.ts: a package it imports is not installed. Run \`${formatInstallCommand(resolvePackageManager(cwd))}\`, then try again.\nOriginal error: ${message}`);
+		throw err;
+	}
+};
+//#endregion
+export { resolveNeonEnvVars as a, resolveDevEnv as i, MissingBranchContextError as n, ServiceNotOnBranchError as r, DevEnvMismatchError as t };