neon 8.11.0 → 8.11.2

package/dist/_chunks/diff-DhxxbdQE.js

@@ -0,0 +1,178 @@
+import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.js";
+import { log } from "../log.js";
+import { isNeonApiError } from "../api.js";
+import { writer } from "../writer.js";
+import { looksLikeBranchId } from "../utils/formats.js";
+import { fillSingleProject, listAllProjectBranches } from "../utils/enrichers.js";
+import { renderDatabaseSchemaDiff, renderSchemaDiffReport } from "../utils/git_diff.js";
+import chalk from "chalk";
+//#region src/commands/diff.ts
+var diff_exports = /* @__PURE__ */ __exportAll({
+	builder: () => builder,
+	command: () => command,
+	describe: () => describe,
+	handler: () => handler
+});
+const command = "diff [compare-branch]";
+const describe = "Show a git-style schema diff between the current branch and another branch";
+const builder = (argv) => argv.usage("$0 diff [compare-branch] [options]").positional("compare-branch", {
+	describe: "Branch name or id to compare against (the reference / '---' side). Defaults to the current branch's parent.",
+	type: "string"
+}).options({
+	"project-id": {
+		describe: "Project ID",
+		type: "string"
+	},
+	branch: {
+		alias: "b",
+		describe: "The branch to review (the '+++' side). Defaults to the branch pinned in the local context (.neon).",
+		type: "string"
+	},
+	database: {
+		alias: "db",
+		describe: "Limit the diff to a single database. Defaults to every database on the current branch.",
+		type: "string"
+	}
+}).middleware(fillSingleProject).middleware((args) => {
+	const compareBranch = args["compare-branch"];
+	if (typeof compareBranch === "string") args.compareBranch = compareBranch;
+}).example([
+	["$0 diff main", "Diff the current branch's schema against the main branch"],
+	["$0 diff", "Diff the current branch's schema against its parent branch"],
+	["$0 diff main --branch feature/checkout", "Diff an explicit branch against main (ignoring the .neon context)"],
+	["$0 diff main --db neondb", "Diff only the neondb database against main"]
+]);
+const handler = async (props) => {
+	const branches = await listAllProjectBranches(props.apiClient, props.projectId);
+	const after = resolveAfterBranch(branches, props.branch);
+	const before = resolveBeforeBranch(branches, after, props.compareBranch);
+	if (before.branchId === after.branchId) throw new Error(`Nothing to compare: both sides resolve to branch ${after.branchName} (${after.branchId}).`);
+	const databases = await resolveDatabases(props, after);
+	const diffs = [];
+	for (const database of databases) {
+		const [beforeSql, afterSql] = await Promise.all([fetchSchemaSql(props, before.branchId, database), fetchSchemaSql(props, after.branchId, database)]);
+		diffs.push({
+			database,
+			before: {
+				...before,
+				sql: beforeSql
+			},
+			after: {
+				...after,
+				sql: afterSql
+			}
+		});
+	}
+	if (props.output === "json" || props.output === "yaml") {
+		writeStructured(props, diffs);
+		return;
+	}
+	log.info("%s Comparing schema %s → %s", chalk.dim("→"), chalk.red(`${before.branchName}`), chalk.green(`${after.branchName}`));
+	const { hasChanges, text } = renderSchemaDiffReport(diffs, { color: props.color !== false });
+	if (!hasChanges) {
+		log.info("No schema differences between %s and %s.", before.branchName, after.branchName);
+		return;
+	}
+	writer(props).text(`${text}\n`);
+};
+/**
+* Resolve the branch under review (`+++` side). Prefers the explicit
+* `branch`/`--branch` value (name or `br-…` id), falling back to the project's
+* default branch. An unknown `br-…` id is trusted as-is (it may be too new to
+* appear in the listing); an unknown *name* is a hard error.
+*/
+const resolveAfterBranch = (branches, ref) => {
+	if (ref) return resolveRef(branches, ref);
+	const def = branches.find((b) => b.default);
+	if (!def) throw new Error("No branch specified and no default branch found. Pass --branch <name|id>.");
+	return {
+		branchId: def.id,
+		branchName: def.name ?? def.id
+	};
+};
+/**
+* Resolve the reference branch (`---` side). Uses the `compare-branch`
+* positional when given, otherwise the parent of the branch under review — so a
+* bare `neon diff` answers "what did I change since branching?".
+*/
+const resolveBeforeBranch = (branches, after, ref) => {
+	if (ref) return resolveRef(branches, ref);
+	const parentId = branches.find((b) => b.id === after.branchId)?.parent_id;
+	if (!parentId) throw new Error(`Branch "${after.branchName}" has no parent to compare against. Pass a branch to compare with, e.g. \`neon diff main\`.`);
+	return {
+		branchId: parentId,
+		branchName: branches.find((b) => b.id === parentId)?.name ?? parentId
+	};
+};
+/** Resolve a branch reference (name or `br-…` id) against the fetched listing. */
+const resolveRef = (branches, ref) => {
+	const found = looksLikeBranchId(ref) ? branches.find((b) => b.id === ref) : branches.find((b) => b.name === ref);
+	if (found) return {
+		branchId: found.id,
+		branchName: found.name ?? found.id
+	};
+	if (looksLikeBranchId(ref)) return {
+		branchId: ref,
+		branchName: ref
+	};
+	throw new Error(`Branch ${ref} not found.\nAvailable branches: ${branches.map((b) => b.name).join(", ")}`);
+};
+/**
+* The databases to diff: the one passed via `--database` (validated against the
+* branch under review), or every database on that branch when none is given.
+*/
+const resolveDatabases = async (props, after) => {
+	const databases = (await props.apiClient.listProjectBranchDatabases(props.projectId, after.branchId)).data.databases;
+	if (props.database !== void 0) {
+		if (!databases.find((d) => d.name === props.database)) throw new Error(`Database "${props.database}" not found on branch ${after.branchName}. Available: ${databases.map((d) => d.name).join(", ")}`);
+		return [props.database];
+	}
+	if (databases.length === 0) throw new Error(`No databases found on branch ${after.branchName} (${after.branchId}).`);
+	return databases.map((d) => d.name);
+};
+/**
+* Fetch a branch database's `CREATE …` SQL. A database absent from the branch
+* (404) yields an empty schema, so the diff shows it as fully added/removed
+* rather than failing — the natural outcome when a database exists on only one
+* side of the comparison.
+*/
+const fetchSchemaSql = async (props, branchId, database) => {
+	try {
+		const { data } = await props.apiClient.getProjectBranchSchema({
+			projectId: props.projectId,
+			branchId,
+			db_name: database
+		});
+		return data.sql ?? "";
+	} catch (err) {
+		if (isNeonApiError(err) && err.status === 404) {
+			log.debug("diff: database %s not found on branch %s; treating schema as empty", database, branchId);
+			return "";
+		}
+		throw err;
+	}
+};
+/** Machine-readable output for `--output json|yaml`: one entry per database. */
+const writeStructured = (props, diffs) => {
+	const report = diffs.map((diff) => {
+		const rendered = renderDatabaseSchemaDiff(diff, { color: false });
+		return {
+			database: diff.database,
+			base_branch: diff.before.branchName,
+			base_branch_id: diff.before.branchId,
+			compare_branch: diff.after.branchName,
+			compare_branch_id: diff.after.branchId,
+			has_changes: rendered.hasChanges,
+			diff: rendered.text
+		};
+	});
+	writer(props).end(report, { fields: [
+		"database",
+		"base_branch",
+		"compare_branch",
+		"has_changes",
+		"diff"
+	] });
+};
+//#endregion
+export { handler as a, diff_exports as i, command as n, describe as r, builder as t };

package/dist/_chunks/docs-CrVybkTP.js

@@ -0,0 +1,197 @@
+import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.js";
+import { getCliAgent, isCi } from "../env.js";
+import pkg_default from "../pkg.js";
+import { isNetworkError } from "../errors.js";
+import { resolveOutputWidth, stripAnsi, truncateTo } from "../human_table.js";
+import { writer } from "../writer.js";
+import { single } from "../utils/flags.js";
+import chalk from "chalk";
+//#region src/commands/docs.ts
+var docs_exports = /* @__PURE__ */ __exportAll({
+	DEFAULT_SITE_SEARCH_URL: () => DEFAULT_SITE_SEARCH_URL,
+	MAX_LIMIT: () => 40,
+	MAX_QUERY_LENGTH: () => 500,
+	SITE_SEARCH_CATEGORIES: () => SITE_SEARCH_CATEGORIES,
+	builder: () => builder,
+	command: () => command,
+	describe: () => describe,
+	formatSearchResults: () => formatSearchResults,
+	parseSearchHits: () => parseSearchHits,
+	resolveSiteSearchUrl: () => resolveSiteSearchUrl,
+	siteSearchHeaders: () => siteSearchHeaders
+});
+const DEFAULT_SITE_SEARCH_URL = "https://br-frosty-cell-a5smzg39-assistant.compute.c-1.us-east-2.aws.neon.tech/site-search";
+const SITE_SEARCH_CATEGORIES = [
+	"docs",
+	"api",
+	"postgresql",
+	"guides",
+	"faqs",
+	"blog",
+	"changelog"
+];
+const MAX_QUERY_LENGTH = 500;
+const MAX_LIMIT = 40;
+const DEFAULT_LIMIT = 10;
+const SEARCH_TIMEOUT_MS = 1e4;
+const command = "docs";
+const describe = "Search neon.com docs, guides, and more";
+const SEARCH_DESCRIBE = "Search neon.com: docs, API reference, PostgreSQL tutorial, guides, FAQs, changelog, and blog";
+const builder = (argv) => argv.usage("$0 docs <sub-command> [options]").command("search <query>", SEARCH_DESCRIBE, (yargs) => yargs.positional("query", {
+	describe: "What to search for",
+	type: "string"
+}).options({
+	category: {
+		describe: "Only return pages in these categories (repeatable)",
+		type: "string",
+		array: true,
+		choices: SITE_SEARCH_CATEGORIES
+	},
+	limit: {
+		describe: `Maximum number of results (1-40)`,
+		type: "number",
+		default: DEFAULT_LIMIT
+	},
+	url: {
+		describe: "Override the site search URL",
+		type: "string",
+		hidden: true,
+		coerce: single("url")
+	}
+}).strict().check((args) => {
+	const query = typeof args.query === "string" ? args.query.trim() : "";
+	if (query === "") throw new Error("<query> needs a value");
+	if (query.length > 500) throw new Error(`<query> must be 500 characters or fewer`);
+	const limit = args.limit;
+	if (!Number.isInteger(limit) || limit < 1 || limit > 40) throw new Error(`--limit must be a whole number from 1 to 40`);
+	return true;
+}).example("$0 docs search \"reset a branch\"", SEARCH_DESCRIBE).example("$0 docs search \"create branch\" --category api --category docs", "Search only the API reference and the docs"), (args) => search(args));
+function resolveSiteSearchUrl(opts) {
+	const fromFlag = opts.url?.trim();
+	if (fromFlag) return fromFlag;
+	const fromEnv = opts.envUrl?.trim();
+	if (fromEnv) return fromEnv;
+	return DEFAULT_SITE_SEARCH_URL;
+}
+const search = async (props) => {
+	const query = props.query.trim();
+	const hits = await searchSite({
+		url: resolveSiteSearchUrl({
+			url: props.url,
+			envUrl: process.env.NEON_SITE_SEARCH_URL
+		}),
+		query,
+		limit: props.limit,
+		categories: props.category ? [...new Set(props.category)] : void 0,
+		headers: siteSearchHeaders({
+			analytics: props.analytics,
+			agent: getCliAgent(process.env),
+			version: pkg_default.version
+		})
+	});
+	const emptyMessage = `No results for "${query}".`;
+	if (props.output === "json" || props.output === "yaml") {
+		writer(props).end(hits, {
+			fields: [
+				"title",
+				"heading",
+				"url"
+			],
+			emptyMessage
+		});
+		return;
+	}
+	const text = formatSearchResults(hits, {
+		emptyMessage,
+		width: resolveOutputWidth(process.stdout, void 0, {
+			stdout: process.stdout,
+			envColumns: process.env.COLUMNS
+		})
+	});
+	process.stdout.write(process.env.NO_COLOR || isCi() ? stripAnsi(text) : text);
+};
+function formatSearchResults(hits, opts) {
+	if (hits.length === 0) return `\n${opts.emptyMessage}\n`;
+	return hits.map((hit) => {
+		const section = sectionOf(hit).split(" > ").filter(Boolean);
+		const line = [hit.title, ...section].join(" › ");
+		const shown = opts.width === void 0 ? line : truncateTo(line, opts.width);
+		return `${chalk.bold(shown)}\n  ${chalk.cyan(hit.url)}\n`;
+	}).join("\n");
+}
+function sectionOf(hit) {
+	const parts = hit.heading.split(" > ");
+	return (parts[0] === hit.title ? parts.slice(1) : parts).join(" > ");
+}
+function siteSearchHeaders(opts) {
+	return {
+		"Content-Type": "application/json",
+		"User-Agent": `neon/${opts.version}`,
+		"x-caller-source": "cli",
+		...opts.agent ? { "x-caller-client": encodeURIComponent(opts.agent) } : {},
+		...opts.analytics ? {} : { "x-caller-analytics": "off" }
+	};
+}
+function isTimeout(error) {
+	return error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError");
+}
+async function searchSite(opts) {
+	const signal = AbortSignal.timeout(SEARCH_TIMEOUT_MS);
+	try {
+		const response = await fetch(opts.url, {
+			method: "POST",
+			headers: opts.headers,
+			body: JSON.stringify({
+				query: opts.query,
+				limit: opts.limit,
+				...opts.categories ? { categories: opts.categories } : {}
+			}),
+			signal
+		});
+		const raw = await response.text();
+		if (!response.ok) throw new Error(searchErrorMessage(raw, response.status));
+		return parseSearchHits(raw);
+	} catch (error) {
+		if (isTimeout(error)) throw new Error("Neon site search did not respond in time.");
+		if (isNetworkError(error)) throw new Error("Could not reach Neon site search. Check your internet connection and try again.");
+		throw error;
+	}
+}
+function parseJson(raw) {
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return;
+	}
+}
+function searchErrorMessage(raw, status) {
+	const body = parseJson(raw);
+	if (status < 500 && typeof body === "object" && body !== null && "error" in body && typeof body.error === "string" && body.error.trim() !== "") return body.error;
+	return `Neon site search failed (HTTP ${status}).`;
+}
+const UNEXPECTED_RESPONSE = "Neon site search returned an unexpected response.";
+function stringField(fields, key) {
+	const field = fields[key];
+	if (typeof field !== "string") throw new Error(UNEXPECTED_RESPONSE);
+	return field;
+}
+function parseSearchHits(raw) {
+	const body = parseJson(raw);
+	if (typeof body !== "object" || body === null || !("hits" in body) || !Array.isArray(body.hits)) throw new Error(UNEXPECTED_RESPONSE);
+	return body.hits.map((hit) => {
+		if (typeof hit !== "object" || hit === null) throw new Error(UNEXPECTED_RESPONSE);
+		const fields = Object.fromEntries(Object.entries(hit));
+		const breadcrumb = fields.breadcrumb;
+		if (!Array.isArray(breadcrumb) || !breadcrumb.every((part) => typeof part === "string")) throw new Error(UNEXPECTED_RESPONSE);
+		return {
+			title: stringField(fields, "title"),
+			url: stringField(fields, "url"),
+			category: stringField(fields, "category"),
+			breadcrumb,
+			heading: stringField(fields, "heading"),
+			excerpt: stringField(fields, "excerpt")
+		};
+	});
+}
+//#endregion
+export { builder as a, docs_exports as c, resolveSiteSearchUrl as d, siteSearchHeaders as f, SITE_SEARCH_CATEGORIES as i, formatSearchResults as l, MAX_LIMIT as n, command as o, MAX_QUERY_LENGTH as r, describe as s, DEFAULT_SITE_SEARCH_URL as t, parseSearchHits as u };

package/dist/_chunks/env-5HS5qQGd.js

@@ -0,0 +1,284 @@
+import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.js";
+import { log } from "../log.js";
+import { ensureGitignored } from "../context.js";
+import { isClaimableEnvTarget } from "../claimable/state.js";
+import { getCliName } from "../utils/cli_name.js";
+import { deprecatedServiceMessage, parseServices, servicesFlagValue, servicesOption } from "../neon_services.js";
+import { mergeEnvFile, readEnvFile, resolveEnvFilePath } from "../env_file.js";
+import { t as NEON_ENV_VAR_KEYS, u as isFunctionBaseUrlKey } from "./env-BpP3Dqpe.js";
+import { ENV_PULL_KEY_HELP, ENV_PULL_SERVICES, envKeysForSelection, envPullFlagValue, ownedEnvServiceKeys, parseEnvPullKeys } from "../env_services.js";
+import { fillSingleProject, resolveBranchRef } from "../utils/enrichers.js";
+import { warnAiGateway } from "../utils/ai_gateway_notice.js";
+import { i as dropClaimableUnsupported, o as resolveNeonEnvVars } from "./env-BNm69Qh8.js";
+import { formatPulledEnv, pulledBranch } from "../commands/env_output.js";
+import { existsSync } from "node:fs";
+import chalk from "chalk";
+//#region src/commands/env.ts
+var env_exports = /* @__PURE__ */ __exportAll({
+	ENV_PULL_SKIPPED_HINT: () => ENV_PULL_SKIPPED_HINT,
+	autoPullEnvAfterPin: () => autoPullEnvAfterPin,
+	builder: () => builder,
+	command: () => "env",
+	describe: () => describe,
+	handler: () => handler,
+	pull: () => pull
+});
+const command = "env";
+const describe = "Manage a branch's Neon env variables locally";
+/**
+* Shown (to stderr) when `link` / `checkout` skip the bundled env pull because the user passed
+* `--no-env-pull`. Names the two ways to get the branch's vars without an on-disk file written
+* eagerly: an explicit `neonctl env pull`, or runtime injection via `neon-env run`.
+*/
+const ENV_PULL_SKIPPED_HINT = `Skipped env pull (--no-env-pull). Run \`${getCliName()} env pull\` to write this branch’s env vars (DATABASE_URL, …) into a local .env, or inject them at runtime with \`neon-env run -- <your dev command>\`.`;
+const builder = (argv) => argv.usage("$0 env <sub-command> [options]").options({
+	"project-id": {
+		describe: "Project ID",
+		type: "string"
+	},
+	branch: {
+		describe: "Branch ID or name",
+		type: "string"
+	}
+}).middleware(fillSingleProject).command("pull", "Write the branch's Neon env variables to a local .env file", (yargs) => yargs.usage("$0 env pull [options]").options({
+	file: {
+		describe: "Target .env file to write, relative to cwd. Defaults to an existing .env, otherwise .env.local, in the project directory (next to .neon, or cwd without one). Only Neon variables are updated; other lines are preserved.",
+		type: "string"
+	},
+	service: servicesOption({
+		key: "service",
+		allowed: ENV_PULL_SERVICES,
+		describe: "Pull only these services' variables",
+		also: "Overrides neon.ts, and prunes only within the services you name. Combines with --env as a union."
+	}),
+	env: {
+		alias: "e",
+		describe: `Pull only these individual variables: ${ENV_PULL_KEY_HELP}. Repeat the flag or comma-separate. Overrides neon.ts. Combines with --service as a union; it never narrows a service bundle.`,
+		type: "array",
+		string: true
+	},
+	config: {
+		describe: "Path to a neon.ts policy (defaults to the neon.ts next to .neon, or in cwd without one)",
+		type: "string"
+	}
+}).epilogue([
+	"",
+	"What gets pulled, in precedence order:",
+	"  1. --service / --env, when given — their union, ignoring neon.ts.",
+	"  2. neon.ts, when the project directory (next to .neon, or cwd",
+	"     without one) has one — including derived function URLs (the",
+	"     function does not have to be deployed).",
+	"  3. Otherwise everything the branch has, plus the AI Gateway —",
+	"     which pulls the default AI Gateway credential.",
+	"",
+	"On an unclaimed Claimable Neon project, neon.ts is still the source",
+	"of truth when it only declares Postgres, Auth, and the Data API.",
+	"A neon.ts that declares Realtime, AI Gateway, Functions, or Object Storage",
+	"fails: those cannot be used until the project is claimed. Without",
+	"a neon.ts, a bare pull writes provisioned Postgres, Auth, and Data",
+	"API. Naming unsupported services with --service / --env warns",
+	"and writes nothing for them.",
+	"",
+	"The pull bundled into link / checkout / config apply follows 2 and 3",
+	"without the AI Gateway, so it never writes a gateway token you did",
+	"not ask for. Run `env pull` to add it."
+].join("\n")).example("$0 env pull", "Write the linked branch's Neon vars into .env.local (or .env if present)").example("$0 env pull --branch preview --file .env.preview", "Pull a specific branch into a specific file").example("$0 env pull -s ai-gateway -s postgres", "Pull only the AI Gateway and Postgres variables").example("$0 env pull -e DATABASE_URL", "Pull only the pooled Postgres connection string").example("$0 env pull -s auth -e DATABASE_URL", "Pull all Auth variables plus DATABASE_URL").example("$0 env pull -s functions", "Pull NEON_FUNCTION_<SLUG>_BASE_URL for every deployed function").example("$0 env pull -e NEON_FUNCTION_HELLO_BASE_URL", "Write that function's production invocation URL (no deploy required)").strict(), async (args) => {
+	const rawServices = servicesFlagValue(args.service);
+	const rawEnvKeys = envPullFlagValue(args.env);
+	const services = rawServices ? parseServices(rawServices, {
+		allowed: ENV_PULL_SERVICES,
+		flag: "--service",
+		onDeprecated: (used, canonical) => log.warning(deprecatedServiceMessage(used, canonical))
+	}) : void 0;
+	const envKeys = rawEnvKeys ? parseEnvPullKeys(rawEnvKeys, "--env") : void 0;
+	await pull({
+		...args,
+		...services ? { services } : {},
+		...envKeys ? { envKeys } : {}
+	}, {
+		announce: true,
+		implyAiGateway: rawServices === void 0 && rawEnvKeys === void 0
+	});
+});
+const handler = (args) => args;
+/** Every OS-level env var name `@neon/env` can emit, used only for reporting. */
+const NEON_VAR_NAMES = Object.values(NEON_ENV_VAR_KEYS).flatMap((group) => Object.values(group));
+/**
+* The Neon env vars `env pull` *owns*, so it removes any that the branch no longer has when
+* it reconciles the local `.env` (see {@link pull}). Scoped to the unambiguously Neon-named
+* vars — the `NEON_*` aliases plus `DATABASE_URL[_UNPOOLED]` — so switching a working
+* directory to a project/branch without Auth / the Data API / Realtime drops the now-stale
+* `NEON_AUTH_*` / `NEON_DATA_API_*` / `NEON_REALTIME_*` lines instead of leaving credentials for features that
+* aren't enabled.
+*
+* Deliberately **excludes** the storage vars Neon projects onto third-party SDK names
+* (`AWS_*`): those collide with credentials a user may set by hand, so `env pull` only ever
+* writes them, never prunes them. The AI Gateway is emitted solely under its Neon-branded
+* vars (`NEON_AI_GATEWAY_*`), which are owned and pruned.
+*/
+const NEON_OWNED_ENV_KEYS = [
+	...Object.values(NEON_ENV_VAR_KEYS.postgres),
+	...Object.values(NEON_ENV_VAR_KEYS.auth),
+	...Object.values(NEON_ENV_VAR_KEYS.dataApi),
+	...Object.values(NEON_ENV_VAR_KEYS.realtime),
+	...Object.values(NEON_ENV_VAR_KEYS.aiGateway)
+];
+const pull = async (props, opts = {}) => {
+	const cwd = props.cwd ?? process.cwd();
+	const claimable = isClaimableEnvTarget({
+		apiHost: props.apiHost,
+		contextFile: props.contextFile,
+		configDir: props.configDir ?? ""
+	});
+	const dropped = claimable && (props.services !== void 0 || props.envKeys !== void 0) ? dropClaimableUnsupported(props.services ?? [], props.envKeys ?? []) : null;
+	const selectionServices = dropped ? dropped.services : props.services ?? [];
+	const selectionEnvKeys = dropped ? dropped.envKeys : props.envKeys ?? [];
+	const selectedKeys = props.services !== void 0 || props.envKeys !== void 0 ? envKeysForSelection(selectionServices, selectionEnvKeys) : void 0;
+	const branch = opts.branch ?? await resolveBranchRef(props);
+	const namedBranch = opts.announce ? branch : void 0;
+	const branchId = branch.branchId;
+	const location = {
+		cwd,
+		contextFile: props.contextFile
+	};
+	const targetPath = resolveEnvFilePath(location, props.file);
+	const fileExisted = existsSync(targetPath);
+	const existingEnv = fileExisted ? readEnvFile(targetPath) : {};
+	const { vars, credential, skipped } = await resolveNeonEnvVars({
+		...location,
+		projectId: props.projectId,
+		branchId,
+		env: {
+			...process.env,
+			...existingEnv
+		},
+		...props.services !== void 0 ? { services: props.services } : {},
+		...props.envKeys !== void 0 ? { envKeys: props.envKeys } : {},
+		...opts.implyAiGateway ? { implyAiGateway: true } : {},
+		omitUnsetFunctionEnv: true,
+		...claimable ? { claimable: true } : {},
+		...props.config ? { config: props.config } : {},
+		...props.apiKey ? { apiKey: props.apiKey } : {},
+		...props.apiHost ? { apiHost: props.apiHost } : {},
+		...props.runtimeApi ? { api: props.runtimeApi } : {}
+	});
+	const neonVars = pickSelectedVars(pickNeonVars(vars), selectedKeys, props.services !== void 0 ? selectionServices : void 0);
+	if (Object.keys(neonVars).length === 0) {
+		if (!(dropped !== null && dropped.services.length === 0 && dropped.envKeys.length === 0 && dropped.skipped.length > 0)) log.info(`No Neon env variables to pull from ${namedBranch ? pulledBranch(namedBranch) : "this branch"}: no DATABASE_URL or enabled Auth / Data API.`);
+		return { status: "empty" };
+	}
+	const { written, removed } = mergeEnvFile(targetPath, neonVars, { managedKeys: managedKeysFor(selectedKeys, unreachedButCurrent(skipped, existingEnv, branchId), existingEnv, props.services !== void 0 ? selectionServices : void 0, props.envKeys !== void 0 ? selectionEnvKeys : void 0) });
+	process.stderr.write(formatPulledEnv({
+		status: "written",
+		written,
+		removed,
+		file: targetPath,
+		...credential && credential.keys.length > 0 ? { credential } : {}
+	}, cwd, namedBranch));
+	if (!fileExisted) ensureGitignored(targetPath);
+	const gatewayBaseUrl = neonVars.NEON_AI_GATEWAY_BASE_URL;
+	const gatewayToken = neonVars.NEON_AI_GATEWAY_TOKEN;
+	if (gatewayBaseUrl && gatewayToken) await warnAiGateway({
+		apiClient: props.apiClient,
+		projectId: props.projectId,
+		branchId,
+		gateway: {
+			baseUrl: gatewayBaseUrl,
+			token: gatewayToken
+		}
+	});
+	return {
+		status: "written",
+		written,
+		removed,
+		file: targetPath,
+		...credential && credential.keys.length > 0 ? { credential } : {},
+		...skipped && skipped.length > 0 ? { skipped } : {}
+	};
+};
+/** Prevents scoped or unavailable services from pruning values they did not resolve. */
+const managedKeysFor = (selectedKeys, unreached, existingEnv, services, envKeys) => {
+	const existingFunctionKeys = Object.keys(existingEnv).filter(isFunctionBaseUrlKey);
+	const namedFunctionKeys = (envKeys ?? []).filter(isFunctionBaseUrlKey);
+	const ownedFunctionKeys = selectedKeys === void 0 || (services?.includes("functions") ?? false) ? existingFunctionKeys : namedFunctionKeys;
+	const owned = selectedKeys ? [...NEON_OWNED_ENV_KEYS.filter((key) => selectedKeys.includes(key)), ...ownedFunctionKeys] : [...NEON_OWNED_ENV_KEYS, ...ownedFunctionKeys];
+	if (unreached.length === 0) return owned;
+	const keep = new Set(ownedEnvServiceKeys(unreached));
+	return owned.filter((key) => {
+		if (unreached.includes("functions") && isFunctionBaseUrlKey(key)) return false;
+		return !keep.has(key);
+	});
+};
+/**
+* Endpoint failure is not evidence that existing values are stale; the gateway host check
+* avoids preserving credentials for a different branch.
+*/
+const unreachedButCurrent = (skipped, existingEnv, branchId) => {
+	if (!skipped) return [];
+	const keep = [];
+	if (skipped.includes("ai-gateway")) {
+		const baseUrl = existingEnv[NEON_ENV_VAR_KEYS.aiGateway.baseUrl];
+		if (baseUrl !== void 0 && isBranchGatewayUrl(baseUrl, branchId)) keep.push("ai-gateway");
+	}
+	if (skipped.includes("functions")) keep.push("functions");
+	return keep;
+};
+/**
+* Whether a persisted `NEON_AI_GATEWAY_BASE_URL` addresses `branchId`'s gateway.
+*
+* Checks the parsed **hostname** against the shape `@neon/env` builds
+* (`<branchId>-api.ai.<host suffix>`), not the raw string: a prefix comparison is satisfied
+* by a URL whose userinfo carries the branch id (`https://<branchId>-api.ai.@other-host/`)
+* while the request actually goes elsewhere. An unparseable value is not this branch's
+* gateway either, which is an answer rather than a swallowed failure.
+*/
+const isBranchGatewayUrl = (baseUrl, branchId) => URL.canParse(baseUrl) && new URL(baseUrl).hostname.startsWith(`${branchId}-api.ai.`);
+/**
+* Narrow the resolved vars to the explicit service/key union. `fetchEnv` may resolve
+* supporting values that were not selected (the direct connection URI derives the AI Gateway
+* host, for example); those must not land in the target file.
+*/
+const pickSelectedVars = (vars, selectedKeys, services) => {
+	if (!selectedKeys) return vars;
+	const wanted = new Set(selectedKeys);
+	const keepFunctionUrls = services?.includes("functions") ?? false;
+	return Object.fromEntries(Object.entries(vars).filter(([key]) => wanted.has(key) || keepFunctionUrls && isFunctionBaseUrlKey(key)));
+};
+/**
+* Pull a freshly-pinned branch's Neon env vars into a local `.env`, bundled into `link` and
+* `checkout` so the branch-first loop is just *link + checkout* — `env pull` runs for you.
+*
+* On by default; `--no-env-pull` opts out (e.g. when env is injected at runtime via
+* `neon-env run` / `neon dev`, or to keep secrets out of the working tree). The pin is the
+* command's primary effect and has already succeeded by the time this runs, so a pull failure
+* degrades to a warning rather than failing the command.
+*/
+const autoPullEnvAfterPin = async (props, branch) => {
+	if (!props.envPull) {
+		log.info(chalk.dim(ENV_PULL_SKIPPED_HINT));
+		return { status: "skipped" };
+	}
+	try {
+		return await pull(props, branch ? { branch } : {});
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		log.warning(`Branch pinned, but pulling its Neon env vars failed: %s
+Run \`${getCliName()} env pull\` once resolved (e.g. \`${getCliName()} deploy\` if a declared service is missing), or inject them at runtime with \`neon-env run -- <your dev command>\`.`, message);
+		return {
+			status: "failed",
+			message
+		};
+	}
+};
+/**
+* Keep only the recognized Neon variables from the resolved set, so a stray inherited
+* value never lands in the user's `.env` file. (Today `resolveNeonEnvVars` only emits Neon
+* vars, but filtering keeps the contract explicit and future-proof.)
+*/
+const pickNeonVars = (vars) => {
+	const out = {};
+	for (const [name, value] of Object.entries(vars)) if (NEON_VAR_NAMES.some((key) => key === name) || isFunctionBaseUrlKey(name)) out[name] = value;
+	return out;
+};
+//#endregion
+export { describe as a, pull as c, command as i, autoPullEnvAfterPin as n, env_exports as o, builder as r, handler as s, ENV_PULL_SKIPPED_HINT as t };