neon 2.46.0 → 3.0.0

package/README.md

@@ -417,9 +417,15 @@ The human-readable summary line goes to stderr and the diff body to stdout, so `
 
 ### env pull
 
-`env pull` writes the linked branch's Neon environment variables into a local dotenv file: an existing `.env` if you have one, otherwise `.env.local` (override with `--file <path>`). Only Neon-managed keys (`DATABASE_URL`, `DATABASE_URL_UNPOOLED`, and the Neon Auth / Data API URLs when those services are enabled) are written; any other lines in the file are preserved. The branch comes from the closest `.neon` file, so no `--branch` is needed (pass `--branch <id|name>` to target another branch).
+`env pull` writes the linked branch's Neon environment variables into a local dotenv file: an existing `.env` if you have one, otherwise `.env.local` (override with `--file <path>`). Only Neon-managed keys are written (see the table below); any other lines in the file are preserved. The branch comes from the closest `.neon` file, so no `--branch` is needed (pass `--branch <id|name>` to target another branch).
 
-`link` and `checkout` invoke `env pull` automatically (see above), so you usually only run it by hand to refresh vars or to pull a different branch into a specific file:
+**What gets pulled**, in precedence order:
+
+1. **`--service`**, when you pass it — exactly those services, whatever else is on the branch and whatever a `neon.ts` says.
+2. **`neon.ts`**, when the working directory has one — the policy is the source of truth, same as `neon dev` and `neon deploy`.
+3. **Everything the branch has** otherwise — Postgres, Neon Auth, the Data API, and object storage read back from the branch, plus the AI Gateway. The gateway has no branch-level state to read back (it is credential-gated, not provisioned), so a bare `env pull` asks for it rather than detecting it, which mints a branch credential. To leave it out, name the services you do want with `--service`.
+
+If the gateway can't be resolved, it is dropped with a warning and the rest of the pull still lands. Gateway variables already in your file for *this* branch are left alone — a pull that couldn't reach the gateway is no evidence the branch has stopped having one — while ones left over from a different branch are pruned like any other stale value.
 
 ```bash
 # Refresh the linked branch's vars in place
@@ -427,10 +433,45 @@ neon env pull
 
 # Pull a specific branch into a specific file
 neon env pull --branch preview --file .env.preview
+
+# Only the AI Gateway
+neon env pull --service ai-gateway
+
+# Repeat the flag or comma-separate; -s, --service and --services are all accepted
+neon env pull -s postgres -s data-api
+neon env pull -s postgres,auth
+```
+
+Every services flag in the CLI takes those three spellings, the same value syntax, and the same service names — see [`config init --services`](#getting-a-neonts-config-init).
+
+| `--service` | Variables |
+| --- | --- |
+| `postgres` | `DATABASE_URL`, `DATABASE_URL_UNPOOLED` |
+| `auth` | `NEON_AUTH_BASE_URL`, `NEON_AUTH_JWKS_URL` |
+| `data-api` | `NEON_DATA_API_URL` |
+| `object-storage` | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_ENDPOINT_URL_S3`, `AWS_REGION` |
+| `ai-gateway` | `NEON_AI_GATEWAY_TOKEN`, `NEON_AI_GATEWAY_BASE_URL` |
+
+`NEON_BRANCH` is written by every pull — it is branch identity, not a service.
+
+**A scoped pull is scoped in both directions.** An unscoped `env pull` owns the Neon-named variables: pointing a directory at a branch without Neon Auth prunes the stale `NEON_AUTH_*` lines. `--service` narrows that to the services you named, so `env pull -s ai-gateway` never touches your `DATABASE_URL`. (`AWS_*` is never pruned by any pull: those names collide with credentials you may set yourself, so `env pull` only ever writes them.)
+
+**A scoped pull also never revokes a credential.** Where an unscoped pull revokes the credential it replaces, a scoped one leaves the old one live — it can't tell which other services still use it. It says so when it happens; revoke it in the Neon Console if nothing does.
+
+Naming a service the branch does not have is an error, not an empty pull:
+
+```
+--service auth: branch br-snowy-frost-12345 has no Neon Auth integration, so there are no
+auth env vars to pull. Provision it first (`neon deploy`, `neon config apply`, or the Neon
+Console), or drop auth from --service.
 ```
 
+`link`, `checkout`, and `config apply` invoke `env pull` automatically (see above). Those bundled pulls follow rules 2 and 3 above **without** the implied AI Gateway: minting a credential for a service you never named isn't something a side effect of another command should do. Run `neon env pull` to get it.
+
 If you'd rather not keep env vars on disk, inject them at runtime instead with `neon-env run -- <your dev command>` (from `@neon/env`) or `neon dev`, and pass `--no-env-pull` to `link` / `checkout`.
 
+**`neon dev` resolves the same set, by the same rules** — including the AI Gateway on a branch with no `neon.ts`. A function running locally gets what the deployed runtime would inject into it, which is the whole point of `dev`; a handler that reads `NEON_AI_GATEWAY_BASE_URL` should not work in production and fail on your machine. `dev` writes nothing, but it does *read* your `.env` / `.env.local` to reuse the branch credential behind the AI Gateway and object storage. Without a file to read from it issues one on every start and leaves the last one live — it has nowhere to keep it, and so cannot name it to revoke it. It says so when it happens; run `env pull` (or just `link` / `checkout`) once and restarts reuse the credential instead.
+
 **Where `.neon` lives**: `link` writes `.neon` into the **current working directory** by default. If an existing `.neon` is found in any parent directory, that file is reused — so commands run from a sub-directory of a linked project still pick up the project's context. To pin the location explicitly, pass `--context-file <path>`.
 
 **`.gitignore` scaffolding**: when `.neon` is **created** for the first time, the CLI also makes sure a `.gitignore` sits alongside it listing `.neon`. If `.gitignore` doesn't exist it's created with a single `.neon` line; if it does exist, `.neon` is appended only when missing (no duplicates, your other entries are left alone). On subsequent updates to an existing `.neon`, `.gitignore` is left untouched — so if you deliberately un-ignore `.neon` (e.g. to commit shared context), the entry is not re-added on every command.
@@ -479,7 +520,10 @@ Selecting nothing is a valid answer: you get the starter policy, which is also w
 neon config init
 
 # Declare services with no prompt
-neon config init --services auth,functions,storage,ai-gateway
+neon config init --services auth,functions,object-storage,ai-gateway
+
+# Repeat the flag instead, and shorten it — every services flag takes all three spellings
+neon config init -s auth -s functions
 
 # Explicitly ask for the bare starter policy
 neon config init --services none
@@ -488,6 +532,8 @@ neon config init --services none
 neon config init --no-install
 ```
 
+Object storage is spelled `object-storage` here, matching [`env pull --service`](#env-pull) and the rest of the CLI. The old `storage` still works and warns; it will be removed.
+
 Choosing **Functions** also writes the handler the policy points at, since `source` is only resolved when `apply` bundles it — a declared function with no file on disk fails at deploy:
 
 ```ts

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

@@ -0,0 +1,558 @@
+/**
+ * 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";
+/**
+ * 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 = 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",
+    },
+};
+export 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;
+}
+/**
+ * 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 };
+}
+/**
+ * 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,
+    });
+}
+/** The `name` this tool stamps on every credential it mints, so it can recognize its own. */
+export 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] : []),
+    ];
+}
+/**
+ * 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]
+            : []),
+    ];
+}
+/**
+ * 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,
+    };
+}
+/**
+ * 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}`;
+}
+/** 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)}`;
+}
+export 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;
+    // 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),
+        },
+    });
+}
+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),
+        },
+    });
+}
+// ───────────────────────── 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;
+}