neon 3.0.0 → 3.1.0

package/dist/_shared/env-core/env.js

@@ -1,558 +1,395 @@
+import { ErrorCode, PlatformError, createNeonApiFromOptions, deriveCredentialScopes, resolveConfig } from "@neon/config/v1";
+//#region src/_shared/env-core/env.ts
 /**
- * The Neon env core — resolving a branch's env from the Neon API, and projecting it into
- * OS-level `{ KEY: value }` pairs.
- *
- * Shared source, not a package: `scripts/sync-shared.mjs` copies it into `@neon/env` (which
- * publishes it as `fetchEnv` / `toEntries`) and into the `neon` CLI (which needs the
- * credential-reuse half in `reuse-secrets.ts`). See `shared/env-core/README.md` for why it is
- * a copy rather than an import.
- *
- * 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.
- */
-import { createNeonApiFromOptions, deriveCredentialScopes, ErrorCode, PlatformError, resolveConfig, } from "@neon/config/v1";
+* The Neon env core — resolving a branch's env from the Neon API, and projecting it into
+* OS-level `{ KEY: value }` pairs.
+*
+* Shared source, not a package: `scripts/sync-shared.mjs` copies it into `@neon/env` (which
+* publishes it as `fetchEnv` / `toEntries`) and into the `neon` CLI (which needs the
+* credential-reuse half in `reuse-secrets.ts`). See `shared/env-core/README.md` for why it is
+* a copy rather than an import.
+*
+* 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}.
- */
+* 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.
- */
+* 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.
- */
+* 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 = new Set([
-    "authenticator",
-    "anonymous",
-    "authenticated",
+* 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"
 ]);
-export 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",
-    },
+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"
+	}
 };
-export async function fetchEnv(config, options) {
-    return fetchEnvKeys(config, options, options.keys ?? null);
+async function fetchEnv(config, options) {
+	return fetchEnvKeys(config, options, options.keys ?? null);
 }
 /**
- * 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.
- */
-export 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 [roles, databases] = await Promise.all([
-        api.listBranchRoles(projectId, branch.id),
-        api.listBranchDatabases(projectId, branch.id),
-    ]);
-    const roleName = pickRoleName(roles, branch, options.roleName);
-    const databaseName = pickDatabaseName(databases, branch, options.databaseName);
-    // Fan out: always fetch both Postgres URIs — the direct one also derives the AI Gateway
-    // host, so a selection that drops `DATABASE_URL_UNPOOLED` still needs it. Conditionally
-    // fetch auth + dataApi based on the branch policy and the selection. Auth key fields are
-    // only returned at integration creation time; for Better Auth they may legitimately be
-    // empty, so they can come back as empty strings.
-    const K = NEON_ENV_VAR_KEYS;
-    const wantsAuth = desired.authEnabled && (wants(K.auth.baseUrl) || wants(K.auth.jwksUrl));
-    const wantsDataApi = desired.dataApiEnabled && wants(K.dataApi.url);
-    const [pooled, unpooled, authSnapshot, dataApiSnapshot] = await Promise.all([
-        api.getConnectionUri(projectId, {
-            branchId: branch.id,
-            databaseName,
-            roleName,
-            pooled: true,
-        }),
-        api.getConnectionUri(projectId, {
-            branchId: branch.id,
-            databaseName,
-            roleName,
-            pooled: false,
-        }),
-        wantsAuth
-            ? api.getNeonAuth(projectId, branch.id)
-            : Promise.resolve(null),
-        wantsDataApi
-            ? api.getNeonDataApi(projectId, branch.id, databaseName)
-            : Promise.resolve(null),
-    ]);
-    const postgres = {};
-    if (wants(K.postgres.databaseUrl))
-        postgres.databaseUrl = pooled.uri;
-    if (wants(K.postgres.databaseUrlUnpooled)) {
-        postgres.databaseUrlUnpooled = unpooled.uri;
-    }
-    if (Object.keys(postgres).length > 0)
-        result.postgres = postgres;
-    // Branch identity, mirroring what the Functions runtime injects on every branch. Surfaced
-    // as `NEON_BRANCH` so local dev (`neon dev` / `neon-env run` / `env pull`) matches the
-    // deployed runtime. Uses the branch name.
-    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) {
-            throw new PlatformError(ErrorCode.NotFound, [
-                `fetchEnv: branch policy enables dataApi but no Data API integration is enabled on branch ${branch.name} (${branch.id}) database ${databaseName}.`,
-                "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,
-                },
-            });
-        }
-        result.dataApi = { url: dataApiSnapshot.url };
-    }
-    // Object storage + AI Gateway (Preview). A single branch credential backs whichever of
-    // these the policy enables; functions never force one but ride along on its scopes. None
-    // of this runs when the policy enables neither, so the Postgres / Auth / Data API path
-    // never touches the credentials/storage endpoints (and keeps working on production, where
-    // they may not exist yet).
-    const storageEnabled = (desired.preview?.buckets.length ?? 0) > 0;
-    const gatewayEnabled = desired.preview?.aiGatewayEnabled ?? false;
-    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));
-    // A credential is minted only for its *secrets*. The endpoint, region and gateway host
-    // are plain branch metadata, so selecting only those touches no credential at all — which
-    // is how a caller holding valid secrets refreshes the rest without issuing a new one.
-    const wantsCredential = (storageEnabled &&
-        (wants(K.storage.accessKeyId) ||
-            wants(K.storage.secretAccessKey))) ||
-        (gatewayEnabled && wants(K.aiGateway.apiKey));
-    if (wantsStorage || wantsGateway) {
-        // Read the branch's storage settings *before* minting: a policy that declares buckets
-        // on a branch without storage has to fail without having spent a credential on a
-        // resolve that cannot succeed.
-        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),
-            })
-            : 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)) {
-                // Bare branch-scoped gateway host derived from the branch's connection URI —
-                // not the control-plane API origin (which doesn't serve the gateway). Clients
-                // append the dialect route (/v1, /openai/v1, /anthropic/v1) themselves.
-                gateway.baseUrl = aiGatewayBaseUrl(branch.id, unpooled.uri);
-            }
-            result.aiGateway = gateway;
-        }
-    }
-    return result;
+* 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 [roles, databases] = await Promise.all([api.listBranchRoles(projectId, branch.id), api.listBranchDatabases(projectId, branch.id)]);
+	const roleName = pickRoleName(roles, branch, options.roleName);
+	const databaseName = pickDatabaseName(databases, branch, options.databaseName);
+	const K = NEON_ENV_VAR_KEYS;
+	const wantsAuth = desired.authEnabled && (wants(K.auth.baseUrl) || wants(K.auth.jwksUrl));
+	const wantsDataApi = desired.dataApiEnabled && wants(K.dataApi.url);
+	const [pooled, unpooled, authSnapshot, dataApiSnapshot] = await Promise.all([
+		api.getConnectionUri(projectId, {
+			branchId: branch.id,
+			databaseName,
+			roleName,
+			pooled: true
+		}),
+		api.getConnectionUri(projectId, {
+			branchId: branch.id,
+			databaseName,
+			roleName,
+			pooled: false
+		}),
+		wantsAuth ? api.getNeonAuth(projectId, branch.id) : Promise.resolve(null),
+		wantsDataApi ? api.getNeonDataApi(projectId, branch.id, databaseName) : Promise.resolve(null)
+	]);
+	const postgres = {};
+	if (wants(K.postgres.databaseUrl)) postgres.databaseUrl = pooled.uri;
+	if (wants(K.postgres.databaseUrlUnpooled)) postgres.databaseUrlUnpooled = unpooled.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) throw new PlatformError(ErrorCode.NotFound, [`fetchEnv: branch policy enables dataApi but no Data API integration is enabled on branch ${branch.name} (${branch.id}) database ${databaseName}.`, "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
+		} });
+		result.dataApi = { url: dataApiSnapshot.url };
+	}
+	const storageEnabled = (desired.preview?.buckets.length ?? 0) > 0;
+	const gatewayEnabled = desired.preview?.aiGatewayEnabled ?? false;
+	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 wantsCredential = storageEnabled && (wants(K.storage.accessKeyId) || wants(K.storage.secretAccessKey)) || gatewayEnabled && wants(K.aiGateway.apiKey);
+	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)
+		}) : 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, unpooled.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.
- */
-export 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);
-    const 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 } : {}),
-    });
-    return { branch, desired };
+* 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. Only object storage
- * and the AI Gateway *require* a credential; functions never force one (they have no credential
- * of their own), but `functions:invoke` is added to the scope set when a credential is already
- * being minted for storage / the AI Gateway, so the one credential can invoke the branch's
- * functions too. Returns `[]` only when nothing credential-bearing is enabled.
- */
-export function previewCredentialScopes(preview) {
-    if (!preview)
-        return [];
-    const storage = preview.buckets.length > 0;
-    const aiGateway = preview.aiGatewayEnabled;
-    if (!storage && !aiGateway)
-        return [];
-    return deriveCredentialScopes({
-        storage,
-        aiGateway,
-        functions: preview.functions.length > 0,
-    });
+* Scopes the branch credential should carry for a resolved branch policy. Only object storage
+* and the AI Gateway *require* a credential; functions never force one (they have no credential
+* of their own), but `functions:invoke` is added to the scope set when a credential is already
+* being minted for storage / the AI Gateway, so the one credential can invoke the branch's
+* functions too. Returns `[]` only when nothing credential-bearing is enabled.
+*/
+function previewCredentialScopes(preview) {
+	if (!preview) return [];
+	const storage = preview.buckets.length > 0;
+	const aiGateway = preview.aiGatewayEnabled;
+	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. */
-export function credentialName(branchName) {
-    return `neon-env ${branchName}`;
+function credentialName(branchName) {
+	return `neon-env ${branchName}`;
 }
 /** The env-var keys a branch credential's secrets surface under, in emit order. */
-export 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] : []),
-    ];
+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.
- */
-export 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]
-            : []),
-    ];
+* 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.
- */
+* 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 {
-        // The storage gateway authenticates against the full token id (e.g.
-        // `nak_live_…`), not the short token id — using the short id yields
-        // `InvalidAccessKeyId` on every S3 request.
-        accessKeyId: minted.tokenId,
-        secretAccessKey: minted.s3SecretAccessKey,
-        apiToken: minted.apiToken,
-    };
+	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.
- */
+* 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 = "";
-    }
-    // Drop the endpoint label (first segment, e.g. `ep-x` / `ep-x-pooler`), keeping the rest
-    // of the host verbatim — including any infra cell prefix (`c-N.`) the gateway routes on:
-    // `[c-N.]<region>.<cloud>.neon.<tld>`.
-    const suffix = connectionHost.split(".").slice(1).join(".");
-    return `${branchId}-api.ai.${suffix}`;
+	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)}`;
+	return `https://${aiGatewayHost(branchId, connectionUri)}`;
 }
-export function createApiFromOptions(options) {
-    return createNeonApiFromOptions("fetchEnv", {
-        ...(options.apiKey ? { apiKey: options.apiKey } : {}),
-        ...(options.apiHost ? { apiHost: options.apiHost } : {}),
-    });
+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.
- */
+* 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})`),
-        },
-    });
+	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;
-    // Multiple roles. Enabling Neon Auth / the Data API provisions the PostgREST roles
-    // (authenticator/anonymous/authenticated) alongside the project owner, so a normal
-    // branch ends up with >1 role even though only the owner backs a `DATABASE_URL`.
-    // Default to Neon's owner role; if the project was created with a custom owner name,
-    // fall back to the single role left after dropping the managed auth roles. Only a
-    // genuinely ambiguous set (more than one app role) still asks the caller to choose.
-    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),
-        },
-    });
+	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 } });
-    }
-    // Prefer Neon's default `neondb`. On the common "added a second database" branch this
-    // auto-picks it, so a lone or `neondb`-including branch resolves without asking.
-    const neondb = databases.find((d) => d.name === NEON_DEFAULT_DATABASE);
-    if (neondb)
-        return neondb.name;
-    if (databases.length === 1)
-        return databases[0].name;
-    // Several databases and no `neondb` to fall back on. Auto-picking any of them would be
-    // perceived as random and is bad DX, so fail loudly and let the caller disambiguate.
-    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),
-        },
-    });
+	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)
+	} });
 }
-// ───────────────────────── env-var mapping helpers ─────────────────────────
 /**
- * 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.
- */
-export function toEntries(env) {
-    const out = {};
-    const put = (key, value) => {
-        if (value !== undefined)
-            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);
-    // Neon-branded gateway vars only: the bearer and the bare branch gateway host
-    // (scheme://host, no path) — the @neon/ai-sdk-provider appends the dialect route
-    // (/v1, /openai/v1, /anthropic/v1) itself (https://github.com/vercel/ai/pull/15997).
-    put(K.aiGateway.apiKey, env.aiGateway?.apiKey);
-    put(K.aiGateway.baseUrl, env.aiGateway?.baseUrl);
-    return out;
+* 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
+export { NEON_ENV_VAR_KEYS, createApiFromOptions, credentialEnvKeys, credentialName, fetchEnv, fetchEnvKeys, policyEnvKeys, previewCredentialScopes, resolveBranchPolicy, toEntries };