neon 8.3.6 → 8.4.2

package/dist/_chunks/{env-L2DPzDAK.js → env-4WGRW2nw.js}

@@ -2,10 +2,11 @@ import { log } from "../log.js";
 import { getCliName } from "../utils/cli_name.js";
 import { declaredNeonServices } from "../config_services.js";
 import { loadProjectConfig } from "../project.js";
-import { a as defaultAiGatewayCredential, c as fetchEnvKeysState, d as isLiveCredential, h as toEntries, i as credentialName, l as functionBaseUrlKey, m as resolveBranchPolicy, n as createApiFromOptions, o as defaultStorageCredential, p as policyEnvKeys, r as credentialEnvKeys, t as NEON_ENV_VAR_KEYS, u as isFunctionBaseUrlKey } from "./env-XsUZj_Ay.js";
+import { a as defaultAiGatewayCredential, c as fetchEnvKeysState, d as isLiveCredential, h as toEntries, i as credentialName, l as functionBaseUrlKey, m as resolveBranchPolicy, n as createApiFromOptions, o as defaultStorageCredential, p as policyEnvKeys, r as credentialEnvKeys, t as NEON_ENV_VAR_KEYS, u as isFunctionBaseUrlKey } from "./env-BpP3Dqpe.js";
 import { ENV_PULL_SERVICES, envKeysForSelection, serviceForEnvKey, servicesForEnvKeys } from "../env_services.js";
+import { StagingOnlyError, assertPolicyAvailable, assertRealtimeAvailable, stagingFeaturesEnabled } from "../utils/staging.js";
 import { formatInstallCommand, resolvePackageManager } from "../utils/package_manager.js";
-import { ErrorCode, createNeonApiFromOptions, isPlatformError } from "@neon/config";
+import { ErrorCode, PlatformError, createNeonApiFromOptions, isPlatformError } from "@neon/config";
 import { credentialScopesSatisfied } from "@neon/config/v1";
 import { plan, pullConfig } from "@neon/config-runtime";
 //#region ../../internals/env-core/dist/reuse-secrets.js
@@ -238,7 +239,8 @@ var ServiceNotOnBranchError = class extends Error {
 const CLAIMABLE_UNSUPPORTED_SERVICES = /* @__PURE__ */ new Set([
 	"ai-gateway",
 	"functions",
-	"object-storage"
+	"object-storage",
+	"realtime"
 ]);
 const CLAIMABLE_RESOLVE_ORDER = [
 	"postgres",
@@ -366,7 +368,7 @@ const resolveClaimableNeonEnvVars = async (ctx) => {
 };
 /**
 * Resolve the branch's Neon env vars (pooled / direct `DATABASE_URL`, plus Auth /
-* Data API when enabled) into a `{ KEY: value }` map. Shared by `neon dev` (which
+* Data API / Realtime when enabled) into a `{ KEY: value }` map. Shared by `neon dev` (which
 * injects them) and `neon env pull` (which writes them to a `.env` file).
 *
 * Tiered:
@@ -382,7 +384,7 @@ const resolveClaimableNeonEnvVars = async (ctx) => {
 *      function still gets `NEON_FUNCTION_*_BASE_URL`. Otherwise `fetchEnv` evaluates
 *      the policy.
 *   2. no `neon.ts`, but a project + branch are known -> `pullConfig` reads the
-*      branch's live state (Auth / Data API enablement plus any object-storage
+*      branch's live state (Auth / Data API / Realtime enablement plus any object-storage
 *      buckets) into a config, then `fetchEnv` resolves what is actually enabled —
 *      so a branch with a bucket gets its `AWS_*` storage vars pulled with no policy.
 *      Function invocation URLs are listed live (`functionUrls: "all-live"`) because
@@ -412,7 +414,8 @@ const resolveNeonEnvVars = async (ctx) => {
 		const pulled = await pullConfig({
 			projectId: ctx.projectId,
 			branchId: ctx.branchId,
-			...apiOptions(ctx)
+			...apiOptions(ctx),
+			realtime: stagingFeaturesEnabled(ctx.apiHost)
 		});
 		const resolvedBranch = {
 			id: pulled.branch.id,
@@ -510,12 +513,14 @@ const resolveSelectedServices = async (ctx, directServices, envKeys) => {
 	const impliedServices = servicesForEnvKeys(envKeys);
 	const services = ENV_PULL_SERVICES.filter((service) => directServices.includes(service) || impliedServices.includes(service));
 	const selectedKeys = envKeysForSelection(directServices, envKeys);
+	if (services.includes("realtime")) assertRealtimeAvailable(ctx.apiHost);
 	const api = apiFor(ctx);
 	const has = (service) => services.includes(service);
 	const checkAiGateway = has("ai-gateway") && !selectedKeys.includes(NEON_ENV_VAR_KEYS.aiGateway.apiKey);
-	const [auth, dataApiEnabled, buckets, aiGatewayAvailable, functions] = await Promise.all([
+	const [auth, dataApiEnabled, realtime, buckets, aiGatewayAvailable, functions] = await Promise.all([
 		has("auth") ? api.getNeonAuth(projectId, branchId) : null,
 		has("data-api") ? readDataApiEnabled(api, projectId, branchId) : null,
+		has("realtime") ? readRealtime(api, projectId, branchId) : null,
 		has("object-storage") ? api.listBranchBuckets(projectId, branchId) : null,
 		checkAiGateway ? readAiGatewayAvailable(api, projectId, branchId) : null,
 		directServices.includes("functions") ? api.listBranchFunctions(projectId, branchId) : null
@@ -527,6 +532,7 @@ const resolveSelectedServices = async (ctx, directServices, envKeys) => {
 	const config = configForServices(services, branchId, {
 		authEnabled: auth !== null,
 		dataApiEnabled,
+		realtimeEnabled: realtime === null ? false : realtime.enabled || realtime.pending,
 		buckets: buckets ?? [],
 		aiGatewayAvailable: aiGatewayAvailable ?? true
 	}, {
@@ -567,6 +573,11 @@ const readAiGatewayAvailable = async (api, projectId, branchId) => {
 		throw error;
 	}
 };
+const readRealtime = async (api, projectId, branchId) => {
+	const getRealtime = api.getProjectBranchRealtime;
+	if (!getRealtime) throw new PlatformError(ErrorCode.FeatureUnavailable, "This NeonApi adapter does not implement getProjectBranchRealtime.");
+	return await getRealtime.call(api, projectId, branchId);
+};
 /** Neon's default database, and the one `fetchEnv` prefers when a branch has several. */
 const NEON_DEFAULT_DATABASE = "neondb";
 /**
@@ -580,6 +591,7 @@ const configForServices = (services, branchId, branch, selection) => {
 	const provisionWith = {
 		auth: `${getCliName()} neon-auth enable`,
 		"data-api": `${getCliName()} data-api create`,
+		realtime: `${getCliName()} realtime enable`,
 		"object-storage": `${getCliName()} buckets create <name>`
 	};
 	const notOnBranch = (service, what) => {
@@ -604,6 +616,10 @@ const configForServices = (services, branchId, branch, selection) => {
 		if (branch.dataApiEnabled === false) notOnBranch("data-api", "Data API integration");
 		config.dataApi = true;
 	}
+	if (services.includes("realtime")) {
+		if (!branch.realtimeEnabled) notOnBranch("realtime", "Realtime integration");
+		config.preview = { realtime: true };
+	}
 	if (services.includes("object-storage")) {
 		if (branch.buckets.length === 0) notOnBranch("object-storage", "object-storage buckets");
 		config.buckets = Object.fromEntries(branch.buckets.map((bucket) => [bucket.name, { access: bucket.accessLevel }]));
@@ -633,7 +649,7 @@ const resolveDevEnv = async (ctx) => {
 			credential
 		};
 	} catch (err) {
-		if (err instanceof DevEnvMismatchError) throw err;
+		if (err instanceof DevEnvMismatchError || err instanceof StagingOnlyError) throw err;
 		if (err instanceof MissingBranchContextError) {
 			log.debug("dev: %s; skipping env injection", err.message);
 			return {
@@ -742,6 +758,7 @@ const loadNeonConfig = async (ctx) => {
 			...ctx.config ? { path: ctx.config } : {},
 			...ctx.omitUnsetFunctionEnv ? { unsetFunctionEnv: "omit" } : {}
 		});
+		assertPolicyAvailable(config, ctx.apiHost);
 		return config;
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);

package/dist/_chunks/{env-XsUZj_Ay.js → env-BpP3Dqpe.js}

@@ -20,7 +20,7 @@ import { ErrorCode, PlatformError, createNeonApiFromOptions, deriveCredentialSco
 * 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}.
+* {@link dataApiEnvSchema} / {@link realtimeEnvSchema}.
 */
 /**
 * Neon's default database, created with every project. When a branch has several databases
@@ -44,6 +44,10 @@ const NEON_ENV_VAR_KEYS = {
 		jwksUrl: "NEON_AUTH_JWKS_URL"
 	},
 	dataApi: { url: "NEON_DATA_API_URL" },
+	realtime: {
+		url: "NEON_REALTIME_URL",
+		secret: "NEON_REALTIME_SECRET"
+	},
 	/**
 	* 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.
@@ -101,6 +105,55 @@ function requiredValue(value, description) {
 	if (value === null) throw new Error(`fetchEnv: missing ${description}.`);
 	return value;
 }
+const REALTIME_POLL_INTERVAL_MS = 1e3;
+/**
+* Wait for asynchronous Realtime provisioning/rotation before reading its secret. The
+* secret endpoint deliberately returns 404 until provisioning finishes, and during a
+* rotation it can still expose the previous key while `pending` is true.
+*/
+async function resolveRealtimeEnv(args) {
+	const getRealtime = args.api.getProjectBranchRealtime;
+	if (!getRealtime) throw new PlatformError(ErrorCode.FeatureUnavailable, "fetchEnv cannot resolve Realtime: this NeonApi adapter does not implement getProjectBranchRealtime.");
+	const getSecret = args.api.getProjectBranchRealtimeSecret;
+	let resolvedEnv;
+	while (resolvedEnv === void 0) {
+		const snapshot = await getRealtime.call(args.api, args.projectId, args.branch.id);
+		if (!snapshot.pending) {
+			if (!snapshot.enabled) throw new PlatformError(ErrorCode.NotFound, [`fetchEnv: branch policy enables realtime but Realtime is disabled on branch ${args.branch.name} (${args.branch.id}).`, "Enable it via `apply(config, { projectId, branchId })` (or `npx neon deploy`) and re-run fetchEnv. Or set realtime to false or omit it."].join(" "), { details: {
+				projectId: args.projectId,
+				branchId: args.branch.id
+			} });
+			let secret;
+			if (args.wantsSecret) {
+				if (!getSecret) throw new PlatformError(ErrorCode.FeatureUnavailable, "fetchEnv cannot resolve NEON_REALTIME_SECRET: this NeonApi adapter does not implement getProjectBranchRealtimeSecret.");
+				secret = await getSecret.call(args.api, args.projectId, args.branch.id);
+			}
+			if (!secret?.pending) resolvedEnv = {
+				...args.wantsUrl ? { url: realtimeWebSocketUrl(requiredRealtimeInvocationUrl(snapshot, args.branch)) } : {},
+				...secret ? { secret: secret.secret } : {}
+			};
+		}
+		if (resolvedEnv === void 0) await new Promise((resolve) => setTimeout(resolve, REALTIME_POLL_INTERVAL_MS));
+	}
+	return resolvedEnv;
+}
+function requiredRealtimeInvocationUrl(snapshot, branch) {
+	if (snapshot.invocationUrl !== void 0 && snapshot.invocationUrl !== "") return snapshot.invocationUrl;
+	throw new PlatformError(ErrorCode.ServerError, `Realtime is enabled on branch ${branch.name} (${branch.id}), but the Neon API returned no invocation URL.`, { details: { branchId: branch.id } });
+}
+/** Normalize the control-plane invocation URL to the WebSocket URL the client SDK needs. */
+function realtimeWebSocketUrl(value) {
+	let parsed;
+	try {
+		parsed = new URL(value);
+	} catch {
+		throw new PlatformError(ErrorCode.ServerError, `Realtime invocation URL is invalid: ${JSON.stringify(value)}.`);
+	}
+	if (parsed.protocol === "https:") parsed.protocol = "wss:";
+	else if (parsed.protocol === "http:") parsed.protocol = "ws:";
+	else if (parsed.protocol !== "wss:" && parsed.protocol !== "ws:") throw new PlatformError(ErrorCode.ServerError, `Realtime invocation URL must use http(s) or ws(s): ${JSON.stringify(value)}.`);
+	return parsed.toString();
+}
 /**
 * 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
@@ -130,6 +183,7 @@ async function fetchEnvKeysState(config, options, keys, policy) {
 	const wantsUnpooled = wants(K.postgres.databaseUrlUnpooled);
 	const wantsAuth = desired.authEnabled && (wants(K.auth.baseUrl) || wants(K.auth.jwksUrl));
 	const wantsDataApi = desired.dataApiEnabled && wants(K.dataApi.url);
+	const wantsRealtime = desired.realtimePolicy === "enabled" && (wants(K.realtime.url) || wants(K.realtime.secret));
 	const gatewayEnabled = desired.preview?.aiGatewayEnabled ?? false;
 	const functionUrlMode = options.functionUrls ?? "policy";
 	const declaredSlugs = (desired.preview?.functions ?? []).map((fn) => fn.slug);
@@ -196,6 +250,19 @@ async function fetchEnvKeysState(config, options, keys, policy) {
 		}
 		result.dataApi = { url: dataApiSnapshot.url };
 	}
+	if (wantsRealtime) {
+		const realtime = await resolveRealtimeEnv({
+			api,
+			projectId,
+			branch,
+			wantsUrl: wants(K.realtime.url),
+			wantsSecret: wants(K.realtime.secret)
+		});
+		const realtimeEnv = {};
+		if (wants(K.realtime.url)) realtimeEnv.url = requiredValue(realtime.url, "WebSocket URL for enabled Realtime");
+		if (wants(K.realtime.secret)) realtimeEnv.secret = requiredValue(realtime.secret, "shared secret for enabled Realtime");
+		result.realtime = realtimeEnv;
+	}
 	const wantsGateway = gatewayEnabled && (wants(K.aiGateway.apiKey) || wants(K.aiGateway.baseUrl));
 	const wantsStorageCredential = storageEnabled && (wants(K.storage.accessKeyId) || wants(K.storage.secretAccessKey));
 	const wantsGatewayCredential = gatewayEnabled && wants(K.aiGateway.apiKey);
@@ -360,6 +427,7 @@ function policyEnvKeys(desired) {
 		K.branch.name,
 		...desired.authEnabled ? [K.auth.baseUrl, K.auth.jwksUrl] : [],
 		...desired.dataApiEnabled ? [K.dataApi.url] : [],
+		...desired.realtimePolicy === "enabled" ? [K.realtime.url, K.realtime.secret] : [],
 		...(desired.preview?.buckets.length ?? 0) > 0 ? [
 			K.storage.accessKeyId,
 			K.storage.secretAccessKey,
@@ -572,6 +640,8 @@ function toEntries(env) {
 	put(K.auth.baseUrl, env.auth?.baseUrl);
 	put(K.auth.jwksUrl, env.auth?.jwksUrl);
 	put(K.dataApi.url, env.dataApi?.url);
+	put(K.realtime.url, env.realtime?.url);
+	put(K.realtime.secret, env.realtime?.secret);
 	put(K.storage.accessKeyId, env.storage?.accessKeyId);
 	put(K.storage.secretAccessKey, env.storage?.secretAccessKey);
 	put(K.storage.endpoint, env.storage?.endpoint);

package/dist/api.js

@@ -644,6 +644,21 @@ const getApiClient = ({ apiKey, apiHost, requestTimeoutMs = REQUEST_TIMEOUT_MS }
 				database_name: databaseName
 			}
 		})),
+		enableProjectBranchRealtime: (projectId, branchId, data) => call(() => raw.enableProjectBranchRealtime({
+			client,
+			path: {
+				project_id: projectId,
+				branch_id: branchId
+			},
+			body: data
+		})),
+		disableProjectBranchRealtime: (projectId, branchId) => call(() => raw.disableProjectBranchRealtime({
+			client,
+			path: {
+				project_id: projectId,
+				branch_id: branchId
+			}
+		})),
 		listProjectVpcEndpoints: (projectId) => call(() => raw.listProjectVpcEndpoints({
 			client,
 			path: { project_id: projectId }

package/dist/commands/claim.js

@@ -7,7 +7,7 @@ import { t as credentialInputs } from "../_chunks/auth_selection-YX5_KZgD.js";
 import { ClaimableClient, ClaimableServiceError } from "../claimable/api.js";
 import { assertionHasExpired, listClaimableCredentials, readClaimableCredentials, readLinkedClaimableCredentials, removeClaimableCredentials, writeClaimableCredentials } from "../claimable/state.js";
 import { NEON_SERVICES, deprecatedServiceMessage, parseServices, servicesFlagValue, servicesOption } from "../neon_services.js";
-import { claimableDataApiCreateBody, declaredNeonServices } from "../config_services.js";
+import { claimableDataApiCreateBody, declaredClaimableNeonServices, isClaimableService } from "../config_services.js";
 import { projectConfigPath } from "../project.js";
 import { resolveEnvFilePath } from "../env_file.js";
 import { writer } from "../writer.js";
@@ -30,6 +30,7 @@ var claim_exports = /* @__PURE__ */ __exportAll({
 	describe: () => describe,
 	handler: () => handler
 });
+const CLAIMABLE_SERVICES = NEON_SERVICES.filter(isClaimableService);
 const CAPABILITY_FOR_SERVICE = {
 	postgres: "postgres",
 	auth: "auth",
@@ -106,7 +107,7 @@ const builder = (argv) => argv.usage("$0 claim <sub-command> [options]").option(
 	hidden: true
 }).command("create", "Create a temporary Neon project without an account", (y) => y.option("service", servicesOption({
 	key: "service",
-	allowed: NEON_SERVICES,
+	allowed: CLAIMABLE_SERVICES,
 	describe: "Services to request for the claimable project",
 	also: "Postgres is always included. Services unavailable before claim are recorded and reported."
 })).option("file", {
@@ -122,12 +123,12 @@ const builder = (argv) => argv.usage("$0 claim <sub-command> [options]").option(
 }).strict().check(noPassthrough("claim create")), async (args) => {
 	const rawServices = servicesFlagValue(args.service);
 	const services = rawServices ? parseServices(rawServices, {
-		allowed: NEON_SERVICES,
+		allowed: CLAIMABLE_SERVICES,
 		flag: "--service",
 		onDeprecated: (used, canonical) => log.warning(deprecatedServiceMessage(used, canonical))
 	}) : [];
 	const policy = await loadCreatePolicy(typeof args.config === "string" ? args.config : void 0, typeof args.contextFile === "string" ? args.contextFile : void 0);
-	const configuredServices = policy ? declaredNeonServices(policy.config) : [];
+	const configuredServices = policy ? declaredClaimableNeonServices(policy.config) : [];
 	const dataApi = policy ? claimableDataApiCreateBody(policy.config) : void 0;
 	await create({
 		...args,

package/dist/commands/config.js

@@ -11,6 +11,7 @@ import { toNeonConfigView } from "../config_format.js";
 import { declaredNeonServices } from "../config_services.js";
 import { loadProjectConfig, neonConfigFilename, projectConfigPath, projectDir } from "../project.js";
 import { loadEnvFileIntoProcess } from "../env_file.js";
+import { assertPolicyAvailable, assertRealtimeAvailable, listedServices, stagingFeaturesEnabled, stagingFeaturesEnabledForArgv } from "../utils/staging.js";
 import { formatInstallCommand, installArgs, resolvePackageManager, runCommand } from "../utils/package_manager.js";
 import { writer } from "../writer.js";
 import { fillSingleProject, resolveBranchRef } from "../utils/enrichers.js";
@@ -26,7 +27,7 @@ import { autoPullEnvAfterPin } from "./env.js";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 import chalk from "chalk";
-import { packagesToStage, previewGaWarningForConfig, resolveConfig } from "@neon/config";
+import { defineConfig, packagesToStage, previewGaWarningForConfig, resolveConfig } from "@neon/config";
 import { PushAbortedError, PushConflictError, apply, assertZipWithinLimits, bundleAsIs, createBranch, describeNativeFinding, enforceLimits, findUndeclaredNativePackages, inspect, isPartialBranchCreateError, plan, resolveEsbuildEntry, traceNativePackages, zipFunctionBundle } from "@neon/config-runtime";
 //#region src/commands/config.ts
 var config_exports = /* @__PURE__ */ __exportAll({
@@ -158,7 +159,11 @@ const missingDependencies = (cwd) => {
 * starter policy, which is what `config init` has always written.
 */
 const resolveServices = async (props) => {
-	if (props.services !== void 0) return parseConfigInitServices(props.services, (used, canonical) => log.warning(deprecatedServiceMessage(used, canonical)));
+	if (props.services !== void 0) {
+		const services = parseConfigInitServices(props.services, (used, canonical) => log.warning(deprecatedServiceMessage(used, canonical)));
+		if (services.includes("realtime")) assertRealtimeAvailable(props.apiHost);
+		return services;
+	}
 	if (props.pickServices) return props.pickServices();
 	if (isCi() || !process.stdout.isTTY) return [];
 	return pickServicesInteractively();
@@ -264,7 +269,10 @@ const initCmd = async (props) => {
 		writeFileSync(join(cwd, "neon.ts"), renderNeonConfig(services));
 		if (!props.silent) {
 			if (services.length === 0) log.info("Created neon.ts with a starter policy.");
-			else log.info("Created neon.ts declaring %s.", services.join(", "));
+			else {
+				const declared = services.map((service) => service === "realtime" ? "Realtime" : service);
+				log.info("Created neon.ts declaring %s.", declared.join(", "));
+			}
 		}
 		if (services.includes("functions")) scaffoldFunction(cwd);
 	}
@@ -287,6 +295,18 @@ const planAdd = (target, configPath, explicitConfig) => {
 	const flag = explicitConfig ? ` --config ${shellQuote(explicitConfig)}` : "";
 	const provision = `Next: \`${cli} config plan${flag}\` to preview, \`${cli} config apply${flag}\` to provision.`;
 	switch (target.kind) {
+		case "realtime": {
+			const realtime = target.allowedOrigins === void 0 ? true : { allowedOrigins: target.allowedOrigins };
+			defineConfig({ preview: { realtime } });
+			return {
+				edit: {
+					kind: "realtime",
+					enabled: true,
+					...target.allowedOrigins !== void 0 ? { allowedOrigins: target.allowedOrigins } : {}
+				},
+				next: provision
+			};
+		}
 		case "service": return {
 			edit: {
 				kind: "service",
@@ -326,7 +346,7 @@ const planAdd = (target, configPath, explicitConfig) => {
 	}
 };
 /**
-* Declare a service, function, or bucket in the project's `neon.ts` with a text edit that
+* Declare a service, feature, function, or bucket in the project's `neon.ts` with a text edit that
 * leaves the rest of the file alone, creating the file (and installing the config packages)
 * when the project has none. Local only, like `config init`.
 */
@@ -346,8 +366,8 @@ const addCmd = async (props) => {
 	const plan = planAdd(props.target, configPath, props.config);
 	const { source, changes } = editNeonConfig(existing ? readFileSync(existing, "utf8") : renderNeonConfig([]), plan.edit);
 	if (changes.length === 0) {
-		if (props.target.kind === "service") {
-			log.info("%s already enables that; nothing to change.", shown(configPath));
+		if (props.target.kind === "service" || props.target.kind === "realtime") {
+			log.info("%s already has the requested configuration; nothing to change.", shown(configPath));
 			return;
 		}
 		throw new Error(`${shown(configPath)} already declares ${props.target.kind} "${props.target.kind === "function" ? props.target.slug : props.target.name}". Edit it there, or pick another name.`);
@@ -436,7 +456,22 @@ const builder = (argv) => argv.usage("$0 config <sub-command> [options]").option
 }))).command("ai-gateway", "Enable the AI Gateway (aiGateway: true)", addSharedOptions, (args) => addCmd(addProps(args, {
 	kind: "service",
 	service: "ai-gateway"
-}))).command("function <slug>", "Declare a Neon Function and create its handler file", (yargs) => addSharedOptions(yargs).example("$0 config add function sendemail", "Creates functions/sendemail.ts and declares it").example("$0 config add function sendemail --source src/send.ts", "Declares an existing handler").positional("slug", {
+}))).command({
+	command: "realtime",
+	describe: stagingFeaturesEnabledForArgv() ? "Enable Realtime (preview.realtime: true)" : false,
+	builder: (yargs) => addSharedOptions(yargs).option("allowed-origin", {
+		describe: "Allowed browser origin (repeatable). \"*\" allows every origin",
+		type: "array",
+		string: true
+	}),
+	handler: (args) => {
+		assertRealtimeAvailable();
+		return addCmd(addProps(args, {
+			kind: "realtime",
+			...args.allowedOrigin !== void 0 ? { allowedOrigins: args.allowedOrigin } : {}
+		}));
+	}
+}).command("function <slug>", "Declare a Neon Function and create its handler file", (yargs) => addSharedOptions(yargs).example("$0 config add function sendemail", "Creates functions/sendemail.ts and declares it").example("$0 config add function sendemail --source src/send.ts", "Declares an existing handler").positional("slug", {
 	describe: "Function slug: 1-20 lowercase letters and digits",
 	type: "string",
 	demandOption: true
@@ -467,7 +502,7 @@ const builder = (argv) => argv.usage("$0 config <sub-command> [options]").option
 	kind: "bucket",
 	name: args.name,
 	access: args.access
-})))).command("init", "Scaffold a neon.ts policy and install the Neon config packages", (yargs) => yargs.options({
+})))).command("init", "Scaffold a neon.ts policy and install the Neon config packages", (yargs) => yargs.strict().options({
 	install: {
 		describe: "Install @neon/config and @neon/env if they're missing. On by default; use --no-install to just print the command.",
 		type: "boolean",
@@ -475,7 +510,7 @@ const builder = (argv) => argv.usage("$0 config <sub-command> [options]").option
 	},
 	services: servicesOption({
 		key: "services",
-		allowed: NEON_SERVICES,
+		allowed: listedServices(NEON_SERVICES),
 		describe: "Services the scaffolded neon.ts declares",
 		also: "postgres alone writes the starter policy; every branch has Postgres. Omitted: pick interactively on a terminal, starter policy in CI or without a TTY."
 	}),
@@ -506,7 +541,8 @@ const liveConfigView = async (opts) => {
 		branchId: opts.branchId,
 		...opts.apiKey ? { apiKey: opts.apiKey } : {},
 		...opts.apiHost ? { apiHost: opts.apiHost } : {},
-		...opts.runtimeApi ? { api: opts.runtimeApi } : {}
+		...opts.runtimeApi ? { api: opts.runtimeApi } : {},
+		realtime: stagingFeaturesEnabled(opts.apiHost)
 	});
 	const resolved = resolveConfig(live.config, {
 		name: live.branch.name,
@@ -533,6 +569,7 @@ const loadConfig = async (props) => {
 		contextFile: props.contextFile,
 		...props.config ? { path: props.config } : {}
 	});
+	assertPolicyAvailable(config, props.apiHost);
 	return config;
 };
 const status = async (props) => {
@@ -957,6 +994,7 @@ const applyPolicyOnCreate = async (props) => {
 		if (/Could not find a Neon config file/i.test(message)) return;
 		throw err;
 	}
+	assertPolicyAvailable(config, props.apiHost);
 	try {
 		warnDeprecatedPreview(config, await warningTargetForExistingBranch({
 			projectId: props.projectId,
@@ -1041,6 +1079,7 @@ const createBranchFromPolicyOnCheckout = async (props) => {
 		if (/Could not find a Neon config file/i.test(message)) return null;
 		throw err;
 	}
+	assertPolicyAvailable(config, props.apiHost);
 	await assertAiGatewayProvisionableFromCreds({
 		projectId: props.projectId,
 		...props.apiKey ? { apiKey: props.apiKey } : {},

package/dist/commands/dev.js

@@ -3,10 +3,10 @@ import { log } from "../log.js";
 import { isClaimableEnvTarget } from "../claimable/state.js";
 import { getCliName } from "../utils/cli_name.js";
 import { readEnvFile, resolveEnvFilePath } from "../env_file.js";
-import { l as functionBaseUrlKey } from "../_chunks/env-XsUZj_Ay.js";
+import { l as functionBaseUrlKey } from "../_chunks/env-BpP3Dqpe.js";
 import { branchIdResolve } from "../utils/enrichers.js";
 import { bundleEntry } from "../utils/esbuild.js";
-import { a as resolveDevEnv } from "../_chunks/env-L2DPzDAK.js";
+import { a as resolveDevEnv } from "../_chunks/env-4WGRW2nw.js";
 import { findConfigFunctionBySource, resolveFunctionsFromConfig } from "../dev/functions.js";
 import { resolveWatchInputs } from "../dev/inputs.js";
 import { existsSync, mkdirSync, rmSync, statSync, writeFileSync } from "node:fs";

package/dist/commands/env.js

@@ -5,11 +5,12 @@ 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 "../_chunks/env-XsUZj_Ay.js";
+import { t as NEON_ENV_VAR_KEYS, u as isFunctionBaseUrlKey } from "../_chunks/env-BpP3Dqpe.js";
 import { ENV_PULL_KEY_HELP, ENV_PULL_SERVICES, envKeysForSelection, envPullFlagValue, ownedEnvServiceKeys, parseEnvPullKeys } from "../env_services.js";
+import { listedServices } from "../utils/staging.js";
 import { fillSingleProject, resolveBranchRef } from "../utils/enrichers.js";
 import { warnAiGateway } from "../utils/ai_gateway_notice.js";
-import { i as dropClaimableUnsupported, o as resolveNeonEnvVars } from "../_chunks/env-L2DPzDAK.js";
+import { i as dropClaimableUnsupported, o as resolveNeonEnvVars } from "../_chunks/env-4WGRW2nw.js";
 import { formatPulledEnv, pulledBranch } from "./env_output.js";
 import { existsSync } from "node:fs";
 import chalk from "chalk";
@@ -47,7 +48,7 @@ const builder = (argv) => argv.usage("$0 env <sub-command> [options]").options({
 	},
 	service: servicesOption({
 		key: "service",
-		allowed: ENV_PULL_SERVICES,
+		allowed: listedServices(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."
 	}),
@@ -73,7 +74,7 @@ const builder = (argv) => argv.usage("$0 env <sub-command> [options]").options({
 	"",
 	"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 AI Gateway, Functions, or Object Storage",
+	"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",
@@ -107,8 +108,8 @@ const NEON_VAR_NAMES = Object.values(NEON_ENV_VAR_KEYS).flatMap((group) => Objec
 * 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 drops the now-stale
-* `NEON_AUTH_*` / `NEON_DATA_API_*` lines instead of leaving credentials for features that
+* 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
@@ -120,6 +121,7 @@ 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 = {}) => {

package/dist/commands/env_output.js

@@ -1,5 +1,5 @@
 import { NEON_SERVICES, NEON_SERVICE_LABELS } from "../neon_services.js";
-import { u as isFunctionBaseUrlKey } from "../_chunks/env-XsUZj_Ay.js";
+import { u as isFunctionBaseUrlKey } from "../_chunks/env-BpP3Dqpe.js";
 import { BRANCH_ENV_KEY, ENV_PULL_KEYS, serviceForEnvKey } from "../env_services.js";
 import { isAbsolute, relative } from "node:path";
 import { homedir } from "node:os";

package/dist/commands/index.js

@@ -34,10 +34,12 @@ import { t as operations_exports } from "./operations.js";
 import { t as orgs_exports } from "./orgs.js";
 import { t as profile_exports } from "./profile.js";
 import { t as psql_exports } from "./psql.js";
+import { t as realtime_exports } from "./realtime.js";
 import { t as roles_exports } from "./roles.js";
 import { t as set_context_exports } from "./set_context.js";
 import { t as snapshots_exports } from "./snapshots.js";
 import { t as status_exports } from "./status.js";
+import { t as subscribe_exports } from "./subscribe.js";
 import { t as triggers_exports } from "./triggers.js";
 import { t as user_exports } from "./user.js";
 import { t as vpc_endpoints_exports } from "./vpc_endpoints.js";
@@ -75,6 +77,8 @@ var commands_default = [
 	ask_exports,
 	feedback_exports,
 	data_api_exports,
+	realtime_exports,
+	subscribe_exports,
 	functions_exports,
 	triggers_exports,
 	credentials_exports,

package/dist/commands/init.js

@@ -2,6 +2,7 @@ import { t as __exportAll } from "../_chunks/rolldown-runtime-8H4AJuhK.js";
 import { getCliName } from "../utils/cli_name.js";
 import { helpCsv, helpEpilogue } from "../utils/help_text.js";
 import { NEON_SERVICES, servicesOption } from "../neon_services.js";
+import { listedServices } from "../utils/staging.js";
 import { coerceAgentFlag } from "../utils/agent_flag.js";
 import { initPluginAgents, initSkillsMcpAgents } from "../init/plan.js";
 import { listSkillIds } from "../skills/catalog.js";
@@ -51,7 +52,7 @@ const builder = (yargs) => yargs.usage("$0 init [options]").option("context-file
 	describe: "Create neon.ts after linking. Use --no-config to skip. Omitted in Custom: you will be asked"
 }).option("services", servicesOption({
 	key: "services",
-	allowed: NEON_SERVICES,
+	allowed: listedServices(NEON_SERVICES),
 	describe: "Services to declare in neon.ts",
 	also: "postgres alone writes the starter policy; every branch has Postgres. Implies creating neon.ts. Cannot be combined with --no-config."
 })).option("org-id", {

package/dist/commands/manifest.js

@@ -1,4 +1,5 @@
 import { getCliName } from "../utils/cli_name.js";
+import { REALTIME_COMING_SOON } from "../utils/staging.js";
 import { Parser } from "yargs/helpers";
 //#region src/commands/manifest.ts
 /**
@@ -186,6 +187,18 @@ const commandManifest = [
 		describe: "Manage the Neon Data API for a database",
 		load: () => import("./data_api.js")
 	},
+	{
+		command: "realtime",
+		describe: "Manage Neon Realtime for a branch",
+		load: () => import("./realtime.js"),
+		stagingOnly: REALTIME_COMING_SOON
+	},
+	{
+		command: "subscribe <query>",
+		describe: "Subscribe to a live SQL query with Neon Realtime",
+		load: () => import("./subscribe.js"),
+		stagingOnly: REALTIME_COMING_SOON
+	},
 	{
 		command: "functions",
 		aliases: ["function"],
@@ -302,7 +315,8 @@ const preloadCommand = async (cli, args) => {
 * command still runs, because yargs 17 awaits a builder's promise when it runs a command; shell
 * completion does not await it, so a mispredicted completion lists no subcommands.
 */
-const lazyCommands = commandManifest.map((entry) => ({
+const lazyCommands = ({ staging }) => commandManifest.map((entry) => entry.stagingOnly && !staging ? comingSoonCommand(entry, entry.stagingOnly) : lazyCommand(entry));
+const lazyCommand = (entry) => ({
 	command: entry.command,
 	aliases: entry.aliases,
 	describe: entry.describe,
@@ -316,6 +330,15 @@ const lazyCommands = commandManifest.map((entry) => ({
 	handler: async (args) => {
 		return (loaded.get(entry) ?? await entry.load()).handler?.(args);
 	}
-}));
+});
+const comingSoonCommand = (entry, message) => ({
+	command: `${verbOf(entry)} [args..]`,
+	aliases: entry.aliases,
+	describe: false,
+	builder: () => {
+		throw new Error(message);
+	},
+	handler: () => {}
+});
 //#endregion
 export { commandManifest, lazyCommands, preloadCommand, selectCommand, selectCompletionCommand };