neon 4.13.0 → 4.14.0

package/dist/commands/auth.js

@@ -1,19 +1,21 @@
 import { t as __exportAll } from "../_chunks/rolldown-runtime-8H4AJuhK.js";
-import { a as OAUTH, i as API_KEY, l as interpretCredentials, s as credentialLabel, t as storeFor } from "../_chunks/credential_io-YeAxg9Xn.js";
+import { a as OAUTH, i as API_KEY, l as interpretCredentials, s as credentialLabel, t as storeFor } from "../_chunks/credential_io-D8AR-jvB.js";
 import { isCi } from "../env.js";
 import { log } from "../log.js";
-import { getApiClient } from "../api.js";
-import { a as isOwnedCredentialPath } from "../_chunks/paths-DMq0Lt7a.js";
+import { getApiClient, isNeonApiError } from "../api.js";
 import { setAuthContext } from "../auth_context.js";
+import { a as isOwnedCredentialPath } from "../_chunks/paths-DMq0Lt7a.js";
 import { currentContextFile, isAskCommand, isClaimCommand, isConfigInit, isCurrentBranchProbe, isMcpCommand, isMcpOauth, isPluginsCommand, isProfileCommand, isSkillsCommand, readContextFile } from "../context.js";
 import { _ as upsertProfile, d as newProfileLocation, g as selectProfileName, h as resolveProfile, i as assertValidProfileName, l as locationForName, m as readProfiles, n as KEYRING_CREDENTIALS, p as profilesUsingPath, r as assertProfilesUsable, s as isKeyringPointer, t as DEFAULT_PROFILE, u as locationOf } from "../_chunks/profiles-CvnFEQyd.js";
 import { extendTokenSet } from "../utils/auth.js";
-import { auth, refreshToken } from "../auth.js";
+import { AuthRefreshError, auth, classifyRefreshFailure, refreshToken } from "../auth.js";
 import { i as selectCredential, n as displacedProfileWarning, t as credentialInputs } from "../_chunks/auth_selection-pitMFzDe.js";
 import { ClaimableClient, ClaimableServiceError } from "../claimable/api.js";
 import { assertionHasExpired, claimableCredentialsPath, readClaimableCredentials, resolveClaimableContext, shouldUseClaimableCredentials } from "../claimable/state.js";
+import { withExclusiveLock } from "../refresh_lock.js";
 import { readOutgoingCredential, retirePreviousCredential } from "../retire_credential.js";
 import { existsSync } from "node:fs";
+import { join } from "node:path";
 import { createHash } from "node:crypto";
 //#region src/commands/auth.ts
 var auth_exports = /* @__PURE__ */ __exportAll({
@@ -25,7 +27,9 @@ var auth_exports = /* @__PURE__ */ __exportAll({
 	describe: () => describe,
 	ensureAuth: () => ensureAuth,
 	handler: () => handler,
+	isAccessTokenUsable: () => isAccessTokenUsable,
 	locationForAuth: () => locationForAuth,
+	refreshStoredCredentials: () => refreshStoredCredentials,
 	usableCredential: () => usableCredential
 });
 const locationForAuth = (configDir, name, keyring, options = {}) => {
@@ -78,7 +82,7 @@ const authFlow = async ({ configDir, oauthHost, clientId, apiHost, forceAuth, "f
 	});
 	let identity = {};
 	try {
-		identity = await preserveCredentials(at, tokenSet, getApiClient({
+		identity = await persistNewSession(at, tokenSet, getApiClient({
 			apiKey: tokenSet.access_token || "",
 			apiHost
 		}), configDir);
@@ -125,67 +129,136 @@ const authFlow = async ({ configDir, oauthHost, clientId, apiHost, forceAuth, "f
 	return tokenSet.access_token || "";
 };
 /**
-* Persist the token set and return the account it belongs to, so a named profile can be
-* labelled with an email. The credentials file records only `user_id` — a UUID with no
-* email — which is why identifying a stored profile offline is otherwise impossible.
+* Persist before identity lookup so a lookup failure cannot discard the new session.
+* Merge the identity only while that session remains current on disk.
 */
-const preserveCredentials = async (at, credentials, apiClient, configDir) => {
-	const { data: { id, email } } = await apiClient.getCurrentUserInfo();
-	const stored = {
-		...credentials,
-		type: OAUTH,
-		...id !== void 0 ? { user_id: id } : {}
-	};
-	storeFor(configDir).write(at, stored);
-	log.debug("Saved credentials to %s", credentialLabel(at));
-	log.debug("Credentials MD5 hash: %s", md5hash(JSON.stringify(stored)));
-	return {
-		...id ? { id } : {},
-		...email ? { email } : {}
-	};
+const persistNewSession = async (at, credentials, apiClient, configDir) => {
+	const stored = oauthCredentialsFromTokenSet(credentials, null);
+	writeOAuthCredentials(configDir, at, stored);
+	const identity = await fetchIdentity(apiClient);
+	if (identity.id) {
+		const current = storeFor(configDir).read(at);
+		if (current !== null && current.credentials.access_token === stored.access_token) writeOAuthCredentials(configDir, at, {
+			...current.credentials,
+			user_id: identity.id
+		});
+	}
+	return identity;
+};
+const fetchIdentity = async (apiClient) => {
+	try {
+		const { data: { id, email } } = await apiClient.getCurrentUserInfo();
+		return {
+			...id ? { id } : {},
+			...email ? { email } : {}
+		};
+	} catch (err) {
+		if (isNeonApiError(err) && err.status === 401) throw new Error("Signed in, but the Neon API rejected the new access token. Try `neon auth` again.");
+		log.warning("Signed in, but could not look up the account: %s", err instanceof Error ? err.message : String(err));
+		return {};
+	}
+};
+const isAccessTokenUsable = (credentials, now) => {
+	const token = credentials.access_token;
+	if (typeof token !== "string" || token === "") return false;
+	const expiresAt = credentials.expires_at;
+	if (typeof expiresAt !== "number" || !Number.isFinite(expiresAt)) return false;
+	return expiresAt > now;
 };
 const handleExistingToken = async (tokenSet, props, at) => {
-	if (tokenSet.access_token && tokenSet.expires_at > Date.now()) {
+	if (isAccessTokenUsable(tokenSet, Date.now())) {
 		log.debug("Using existing valid access_token");
-		const apiClient = getApiClient({
-			apiKey: tokenSet.access_token,
-			apiHost: props.apiHost
-		});
+		const apiKey = tokenSet.access_token ?? "";
 		return {
-			apiKey: tokenSet.access_token,
-			apiClient
+			apiKey,
+			apiClient: getApiClient({
+				apiKey,
+				apiHost: props.apiHost
+			}),
+			refreshed: false
 		};
 	}
-	log.debug(tokenSet.expires_at < Date.now() ? "Token is expired, attempting refresh" : "Token is missing access_token, attempting refresh");
-	if (!tokenSet.refresh_token) {
-		log.debug("TokenSet is missing refresh_token, starting authentication");
+	if (typeof tokenSet.refresh_token !== "string" || tokenSet.refresh_token === "") {
+		log.debug("Stored credentials hold no refresh_token");
 		return null;
 	}
-	let refreshedTokenSet;
-	try {
-		refreshedTokenSet = extendTokenSet(await refreshToken({
-			oauthHost: props.oauthHost,
-			clientId: props.clientId,
-			allowUnsafeTls: props.allowUnsafeTls
-		}, tokenSet));
-	} catch (err) {
-		const typedErr = err instanceof Error ? err : /* @__PURE__ */ new Error("Unknown error");
-		log.debug("Failed to refresh token: %s", typedErr.message);
-		throw new Error("AUTH_REFRESH_FAILED");
-	}
-	const apiKey = refreshedTokenSet.access_token;
-	const apiClient = getApiClient({
-		apiKey,
-		apiHost: props.apiHost
-	});
-	await preserveCredentials(at, refreshedTokenSet, apiClient, props.configDir);
-	log.debug("Token refresh successful");
+	log.debug("Access token is missing or expired, attempting refresh");
+	const next = await performRefresh(tokenSet, props, at);
+	const apiKey = next.credentials.access_token ?? "";
 	return {
 		apiKey,
-		apiClient
+		apiClient: getApiClient({
+			apiKey,
+			apiHost: props.apiHost
+		}),
+		refreshed: next.rotated
 	};
 };
 /**
+* Serialize exchanges because presenting a one-time refresh token twice can revoke
+* the newly issued token family. Persist immediately because the presented token is
+* invalid once the server answers.
+*/
+const performRefresh = async (credentials, props, at) => {
+	return await withExclusiveLock(refreshLockPath(props.configDir, at), async () => {
+		const loaded = storeFor(props.configDir).read(at);
+		const current = loaded?.credentials ?? credentials;
+		if (loaded !== null && isAccessTokenUsable(current, Date.now()) && current.access_token !== credentials.access_token) {
+			log.debug("Refresh lost a race; adopting the credentials another command wrote");
+			return {
+				credentials: current,
+				rotated: false
+			};
+		}
+		let refreshed;
+		try {
+			refreshed = extendTokenSet(await refreshToken({
+				oauthHost: props.oauthHost,
+				clientId: props.clientId,
+				allowUnsafeTls: props.allowUnsafeTls
+			}, current));
+		} catch (err) {
+			throw err instanceof AuthRefreshError ? err : classifyRefreshFailure(err);
+		}
+		const next = oauthCredentialsFromTokenSet(refreshed, loaded?.credentials ?? credentials);
+		writeOAuthCredentials(props.configDir, at, next, { restorePrevious: false });
+		log.debug("Token refresh successful");
+		return {
+			credentials: next,
+			rotated: true
+		};
+	});
+};
+/** A 401 proves the access token is stale even before `expires_at`. */
+const refreshStoredCredentials = async (at, props) => {
+	const loaded = storeFor(props.configDir).read(at);
+	if (loaded === null) return false;
+	if (interpretCredentials(loaded.credentials, at, loaded.backend).kind === "api_key") return false;
+	if (typeof loaded.credentials.refresh_token !== "string" || loaded.credentials.refresh_token === "") return false;
+	await performRefresh(loaded.credentials, props, at);
+	return true;
+};
+const oauthCredentialsFromTokenSet = (tokenSet, previous) => {
+	const refreshTokenValue = typeof tokenSet.refresh_token === "string" && tokenSet.refresh_token !== "" ? tokenSet.refresh_token : previous?.refresh_token;
+	const stored = {
+		...tokenSet,
+		type: OAUTH,
+		expires_at: tokenSet.expires_at,
+		...typeof refreshTokenValue === "string" && refreshTokenValue !== "" ? { refresh_token: refreshTokenValue } : {}
+	};
+	if (previous?.user_id !== void 0) stored.user_id = previous.user_id;
+	return stored;
+};
+const writeOAuthCredentials = (configDir, at, credentials, options) => {
+	storeFor(configDir).write(at, credentials, options);
+	log.debug("Saved credentials to %s", credentialLabel(at));
+	log.debug("Credentials MD5 hash: %s", md5hash(JSON.stringify(credentials)));
+};
+const refreshLockPath = (configDir, at) => {
+	const id = createHash("sha256").update(credentialLabel(at)).digest("hex").slice(0, 16);
+	return join(configDir, `.refresh-${id}.lock`);
+};
+/**
 * The credential a stored file can authenticate with right now — its API key, or an OAuth
 * access token, refreshed first when it has expired. Never launches a browser.
 *
@@ -316,6 +389,17 @@ const ensureAuth = async (props) => {
 			return;
 		}
 		try {
+			setAuthContext({
+				source: "stored-credentials",
+				configDir: props.configDir,
+				profile: selection.profile,
+				storage: at.storage,
+				accessToken: loaded.credentials.access_token,
+				refreshed: false,
+				oauthHost: props.oauthHost,
+				clientId: props.clientId,
+				...at.storage === "file" ? { credentialsPath: at.path } : {}
+			});
 			const result = await handleExistingToken(loaded.credentials, props, at);
 			if (result) {
 				props.apiKey = result.apiKey;
@@ -325,13 +409,23 @@ const ensureAuth = async (props) => {
 					configDir: props.configDir,
 					profile: selection.profile,
 					storage: at.storage,
+					accessToken: result.apiKey,
+					refreshed: result.refreshed,
+					oauthHost: props.oauthHost,
+					clientId: props.clientId,
 					...at.storage === "file" ? { credentialsPath: at.path } : {}
 				});
 				return;
 			}
 		} catch (err) {
-			if (!(err instanceof Error && err.message === "AUTH_REFRESH_FAILED")) throw err;
-			log.debug("Ensure auth failed, starting authentication", err);
+			if (err instanceof AuthRefreshError) {
+				if (isLocalDev || isBootstrap || isMcp) {
+					log.warning("%s Continuing without credentials.", err.message);
+					return;
+				}
+				throw err;
+			}
+			throw err;
 		}
 	} else log.debug("No usable credentials at %s, starting authentication", credentialLabel(at));
 	if (isLocalDev) {
@@ -360,18 +454,16 @@ const ensureAuth = async (props) => {
 		configDir: props.configDir,
 		profile: selection.profile,
 		storage: at.storage,
+		accessToken: apiKey,
+		refreshed: true,
+		oauthHost: props.oauthHost,
+		clientId: props.clientId,
 		...at.storage === "file" ? { credentialsPath: at.path } : {}
 	});
 };
 /**
-* Delete one credentials file — used by the 401 handler to clear an OAuth token set the API
-* has rejected, so the next command logs in again instead of failing the same way.
-*
-* It takes the exact path rather than a directory and an optional profile. Deriving the path
-* here meant re-running selection from partial state, and the 401 handler has no parsed
-* arguments: it passed only the config directory, so a rejected token on a
-* `--profile`-selected account deleted whatever `DEFAULT` pointed at — signing the user out
-* of an account whose credentials the failed request had never touched.
+* Accept an exact location because deriving it from a config directory used to
+* delete DEFAULT when a named profile failed.
 */
 const deleteCredentialsAt = (at, configDir) => {
 	try {
@@ -388,4 +480,4 @@ const deleteCredentialsAt = (at, configDir) => {
 };
 const md5hash = (s) => createHash("md5").update(s).digest("hex");
 //#endregion
-export { aliases, authFlow, builder, command, deleteCredentialsAt, describe, ensureAuth, handler, locationForAuth, auth_exports as t, usableCredential };
+export { aliases, authFlow, builder, command, deleteCredentialsAt, describe, ensureAuth, handler, isAccessTokenUsable, locationForAuth, refreshStoredCredentials, auth_exports as t, usableCredential };

package/dist/commands/checkout.js

@@ -8,7 +8,7 @@ import { looksLikeBranchId } from "../utils/formats.js";
 import { fillSingleProject } from "../utils/enrichers.js";
 import { createBranch, pickBranchInteractively } from "../utils/branch_picker.js";
 import { autoPullEnvAfterPin } from "./env.js";
-import { applyPolicyOnCreate, createBranchFromPolicyOnCheckout } from "./config.js";
+import { applyPolicyOnCreate, createBranchFromPolicyOnCheckout, envFlag } from "./config.js";
 import { handler as handler$1 } from "./link.js";
 import chalk from "chalk";
 import prompts from "prompts";
@@ -17,10 +17,20 @@ var checkout_exports = /* @__PURE__ */ __exportAll({
 	builder: () => builder,
 	command: () => command,
 	describe: () => describe,
+	formatCheckoutPolicyFailure: () => formatCheckoutPolicyFailure,
 	handler: () => handler
 });
 const command = "checkout [id|name]";
 const describe = "Pin a branch in the local context (.neon) so subsequent commands target it";
+const formatCheckoutPolicyFailure = (opts) => {
+	const cli = getCliName();
+	const envArg = opts.env ? ` --env ${opts.env}` : "";
+	return [
+		`Branch ${opts.branchName} (${opts.branchId}) was created and checked out, but applying neon.ts to it failed: ${opts.failure}`,
+		`The branch is usable but does not match the policy, and \`${cli} checkout\` never reconciles a branch that already exists.`,
+		`Fix the cause above, then run \`${cli} deploy --update-existing${envArg}\` to apply the policy to it — or, if your policy only configures new branches (keyed on \`!branch.exists\`), delete the branch and check it out again: \`${cli} branches delete ${opts.branchName}\` then \`${cli} checkout ${opts.branchName}${envArg}\`.`
+	].join("\n");
+};
 const builder = (argv) => argv.usage("$0 checkout [id|name] [options]").positional("id", {
 	describe: "Branch name or id to check out. Omit to pick interactively from the list of branches.",
 	type: "string"
@@ -33,10 +43,16 @@ const builder = (argv) => argv.usage("$0 checkout [id|name] [options]").position
 		describe: "Pull the branch's Neon env vars (DATABASE_URL, …) into a local .env after checkout. On by default; use --no-env-pull to skip (e.g. when injecting env at runtime with `neon-env run` / `neon dev`).",
 		type: "boolean",
 		default: true
+	},
+	...envFlag,
+	env: {
+		...envFlag.env,
+		describe: envFlag.env.describe + " Used when this checkout creates a branch from neon.ts; ignored for an existing branch."
 	}
 }).example([
 	["$0 checkout", "Pick a branch interactively from the project in the closest .neon file"],
 	["$0 checkout main", "Pin the branch named \"main\" in the closest .neon file"],
+	["$0 checkout feat --env .env.local", "Create feat from neon.ts, loading Function env from .env.local first"],
 	["$0 checkout br-cool-snow-12345678 --project-id project-id-123", "Pin a branch by id for an explicit project"]
 ]);
 const handler = async (props) => {
@@ -56,7 +72,8 @@ const handler = async (props) => {
 		branchId,
 		...props.apiKey ? { apiKey: props.apiKey } : {},
 		...props.apiHost ? { apiHost: props.apiHost } : {},
-		...props.color !== void 0 ? { color: props.color } : {}
+		...props.color !== void 0 ? { color: props.color } : {},
+		...props.env ? { env: props.env } : {}
 	}) : policyFailure;
 	await autoPullEnvAfterPin({
 		...props,
@@ -64,11 +81,12 @@ const handler = async (props) => {
 		branch: branchId,
 		envPull: props.envPull
 	});
-	if (failure) throw new Error([
-		`Branch ${branchName} (${branchId}) was created and checked out, but applying neon.ts to it failed: ${failure}`,
-		`The branch is usable but does not match the policy, and \`${getCliName()} checkout\` never reconciles a branch that already exists.`,
-		`Fix the cause above, then run \`${getCliName()} deploy --update-existing\` to apply the policy to it — or, if your policy only configures new branches (keyed on \`!branch.exists\`), delete the branch and check it out again: \`${getCliName()} branches delete ${branchName}\` then \`${getCliName()} checkout ${branchName}\`.`
-	].join("\n"));
+	if (failure) throw new Error(formatCheckoutPolicyFailure({
+		branchName,
+		branchId,
+		failure,
+		...props.env ? { env: props.env } : {}
+	}));
 };
 /**
 * Apply the policy to a branch `checkout` just created bare, returning the failure message
@@ -143,7 +161,8 @@ const createCheckoutBranch = async (props, projectId, name, branches) => {
 		branchName: name,
 		...props.apiKey ? { apiKey: props.apiKey } : {},
 		...props.apiHost ? { apiHost: props.apiHost } : {},
-		...props.color !== void 0 ? { color: props.color } : {}
+		...props.color !== void 0 ? { color: props.color } : {},
+		...props.env ? { env: props.env } : {}
 	});
 	if (fromPolicy) return {
 		branchId: fromPolicy.branchId,
@@ -233,4 +252,4 @@ const tryAutoDetectProject = async (props) => {
 	}
 };
 //#endregion
-export { builder, command, describe, handler, checkout_exports as t };
+export { builder, command, describe, formatCheckoutPolicyFailure, handler, checkout_exports as t };

package/dist/commands/claim.js

@@ -2,7 +2,7 @@ import { t as __exportAll } from "../_chunks/rolldown-runtime-8H4AJuhK.js";
 import { isCi } from "../env.js";
 import { log } from "../log.js";
 import { applyContext, contextBranch, ensureGitignored, readContextFile } from "../context.js";
-import { declaredNeonServices } from "../config_services.js";
+import { claimableDataApiCreateBody, declaredNeonServices } from "../config_services.js";
 import { NEON_SERVICES, deprecatedServiceMessage, parseServices, servicesFlagValue, servicesOption } from "../neon_services.js";
 import { mergeEnvFile, resolveEnvFilePath } from "../env_file.js";
 import { t as credentialInputs } from "../_chunks/auth_selection-pitMFzDe.js";
@@ -80,11 +80,11 @@ const findNeonConfig = (cwd = process.cwd()) => {
 		current = parent;
 	}
 };
-const servicesFromConfig = async (explicitPath) => {
+const loadCreatePolicy = async (explicitPath) => {
 	const path = explicitPath ?? findNeonConfig();
-	if (!path) return [];
+	if (!path) return void 0;
 	const { config } = await loadConfigFromFile({ path });
-	return declaredNeonServices(config);
+	return config;
 };
 const removeFileIfPresent = (path) => {
 	try {
@@ -142,10 +142,13 @@ const builder = (argv) => argv.usage("$0 claim <sub-command> [options]").option(
 		flag: "--service",
 		onDeprecated: (used, canonical) => log.warning(deprecatedServiceMessage(used, canonical))
 	}) : [];
-	const configuredServices = await servicesFromConfig(typeof args.config === "string" ? args.config : void 0);
+	const policy = await loadCreatePolicy(typeof args.config === "string" ? args.config : void 0);
+	const configuredServices = policy ? declaredNeonServices(policy) : [];
+	const dataApi = policy ? claimableDataApiCreateBody(policy) : void 0;
 	await create({
 		...args,
-		services: [.../* @__PURE__ */ new Set([...services, ...configuredServices])]
+		services: [.../* @__PURE__ */ new Set([...services, ...configuredServices])],
+		...dataApi ? { dataApi } : {}
 	});
 }).command("status [project-id]", "Show a claimable project's lifecycle and claim status", (y) => y.positional("project-id", {
 	describe: "Project from `neon claim list`. Defaults to the project linked in this directory",
@@ -208,7 +211,8 @@ const create = async (props) => {
 	const client = new ClaimableClient(props.claimableHost);
 	const registration = await client.register({
 		capabilities: claimableCapabilities(props.services ?? []),
-		source: "neon_cli"
+		source: "neon_cli",
+		...props.dataApi ? { dataApi: props.dataApi } : {}
 	});
 	const stored = {
 		version: 1,

package/dist/commands/config.js

@@ -75,12 +75,8 @@ const INSPECT_FIELDS = [
 	"branch",
 	"config"
 ];
-/**
-* Shared `--env` flag for `config plan|apply` and `deploy`. Loads a `.env` into
-* `process.env` before the policy is evaluated.
-*/
 const envFlag = { env: {
-	describe: "Path to a .env file to load into the environment before evaluating neon.ts (so function env values resolve from it). Existing env vars are not overridden.",
+	describe: "Path to a .env file to load into the environment before evaluating neon.ts so Function env values resolve from it. Existing env vars are not overridden. Function env values that read process.env must be set in this file or the environment.",
 	type: "string"
 } };
 /** Apply-only flags, exported so `deploy` can reuse the exact same surface. */
@@ -331,11 +327,13 @@ const liveConfigView = async (opts) => {
 		view: toNeonConfigView(resolved, live.preview)
 	};
 };
+const loadEnvFileIfGiven = (env) => {
+	if (!env) return;
+	const applied = loadEnvFileIntoProcess(env);
+	log.debug("Loaded %d var(s) from %s into the environment: %s", applied.length, env, applied.join(", "));
+};
 const loadConfig = async (props) => {
-	if (props.env) {
-		const applied = loadEnvFileIntoProcess(props.env);
-		log.debug("Loaded %d var(s) from %s into the environment: %s", applied.length, props.env, applied.join(", "));
-	}
+	loadEnvFileIfGiven(props.env);
 	const { config } = await loadConfigFromFile$1({ ...props.config ? { path: props.config } : {} });
 	return config;
 };
@@ -529,6 +527,7 @@ const assertAiGatewayProvisionableFromCreds = async (props) => {
 * see overridden. Functions are bundled with neonctl's own esbuild helper.
 */
 const applyPolicyOnCreate = async (props) => {
+	loadEnvFileIfGiven(props.env);
 	let config;
 	try {
 		({config} = await loadConfigFromFile$1({ ...props.cwd ? { cwd: props.cwd } : {} }));
@@ -588,6 +587,7 @@ const logPolicyResult = (result, opts) => {
 * (see the handler) instead of leaving it stranded behind an unchanged `.neon`.
 */
 const createBranchFromPolicyOnCheckout = async (props) => {
+	loadEnvFileIfGiven(props.env);
 	let config;
 	try {
 		({config} = await loadConfigFromFile$1({ ...props.cwd ? { cwd: props.cwd } : {} }));

package/dist/commands/deploy.js

@@ -1,6 +1,7 @@
 import { t as __exportAll } from "../_chunks/rolldown-runtime-8H4AJuhK.js";
 import { fillSingleProject } from "../utils/enrichers.js";
 import { applyCmd, applyFlags, envFlag, envPullFlag } from "./config.js";
+import { DEPLOY_COMMANDS_EPILOGUE } from "./deploy_help.js";
 //#region src/commands/deploy.ts
 var deploy_exports = /* @__PURE__ */ __exportAll({
 	builder: () => builder,
@@ -26,7 +27,7 @@ const builder = (argv) => argv.usage("$0 deploy [options]").options({
 	...envFlag,
 	...applyFlags,
 	...envPullFlag
-}).middleware(fillSingleProject).strict();
+}).middleware(fillSingleProject).epilogue(DEPLOY_COMMANDS_EPILOGUE).strict();
 const handler = (props) => applyCmd(props);
 //#endregion
 export { builder, command, describe, handler, deploy_exports as t };

package/dist/commands/deploy_help.js

@@ -0,0 +1,10 @@
+//#region src/commands/deploy_help.ts
+const DEPLOY_COMMANDS_EPILOGUE = [
+	"",
+	"Use neon deploy with a neon.ts file for a full deployment (declared services and functions).",
+	"Use neon functions deploy to deploy one function manually, including a targeted env update.",
+	"neon deploy --env <file> loads that .env file so neon.ts can read Function env from it.",
+	"neon functions deploy --env is KEY=VALUE (repeatable), not a file path."
+].join("\n");
+//#endregion
+export { DEPLOY_COMMANDS_EPILOGUE };