neon 3.0.0 → 3.1.0

package/dist/dev/env.js

@@ -1,446 +1,365 @@
-import { createNeonApiFromOptions, loadConfigFromFile, } from "@neon/config";
-import { plan, pullConfig } from "@neon/config-runtime";
-import { NEON_ENV_VAR_KEYS } from "../_shared/env-core/env.js";
-import { fetchEnvReusingSecrets, } from "../_shared/env-core/reuse-secrets.js";
 import { log } from "../log.js";
 import { getCliName } from "../utils/cli_name.js";
+import { NEON_ENV_VAR_KEYS } from "../_shared/env-core/env.js";
+import { formatInstallCommand, resolvePackageManager } from "../utils/package_manager.js";
+import { fetchEnvReusingSecrets } from "../_shared/env-core/reuse-secrets.js";
+import { createNeonApiFromOptions, loadConfigFromFile } from "@neon/config";
+import { plan, pullConfig } from "@neon/config-runtime";
+//#region src/dev/env.ts
 /** The API-targeting options every runtime call forwards from the context. */
 const apiOptions = (ctx) => ({
-    ...(ctx.apiKey ? { apiKey: ctx.apiKey } : {}),
-    ...(ctx.apiHost ? { apiHost: ctx.apiHost } : {}),
-    ...(ctx.api ? { api: ctx.api } : {}),
+	...ctx.apiKey ? { apiKey: ctx.apiKey } : {},
+	...ctx.apiHost ? { apiHost: ctx.apiHost } : {},
+	...ctx.api ? { api: ctx.api } : {}
 });
 /**
- * Thrown when a `neon.ts` policy declares a branch-level resource (Neon Auth,
- * Data API, a bucket, the AI Gateway) that the linked remote branch does not
- * have yet. Unlike every other failure in {@link resolveDevEnv} — which degrades
- * to "run without injection" — this is a hard stop: the user's intent (a policy)
- * cannot be honored, and silently dropping the secret would be more confusing
- * than refusing to start. The fix is to provision the resource first.
- */
-export class DevEnvMismatchError extends Error {
-    constructor() {
-        super(...arguments);
-        this.name = "DevEnvMismatchError";
-    }
-}
+* Thrown when a `neon.ts` policy declares a branch-level resource (Neon Auth,
+* Data API, a bucket, the AI Gateway) that the linked remote branch does not
+* have yet. Unlike every other failure in {@link resolveDevEnv} — which degrades
+* to "run without injection" — this is a hard stop: the user's intent (a policy)
+* cannot be honored, and silently dropping the secret would be more confusing
+* than refusing to start. The fix is to provision the resource first.
+*/
+var DevEnvMismatchError = class extends Error {
+	constructor(..._args) {
+		super(..._args);
+		this.name = "DevEnvMismatchError";
+	}
+};
 /**
- * Signals that no project/branch context could be resolved, so there is nothing to
- * resolve env from. `resolveDevEnv` degrades on this (dev runs without injection);
- * `env pull` surfaces it (an explicit pull needs a branch).
- */
-export class MissingBranchContextError extends Error {
-    constructor() {
-        super(...arguments);
-        this.name = "MissingBranchContextError";
-    }
-}
+* Signals that no project/branch context could be resolved, so there is nothing to
+* resolve env from. `resolveDevEnv` degrades on this (dev runs without injection);
+* `env pull` surfaces it (an explicit pull needs a branch).
+*/
+var MissingBranchContextError = class extends Error {
+	constructor(..._args2) {
+		super(..._args2);
+		this.name = "MissingBranchContextError";
+	}
+};
 /**
- * Thrown when an explicit `--service` selection names a service the branch does not have.
- * Unlike the policy path — where the same situation is a {@link DevEnvMismatchError} pointing
- * at `deploy` — the user named the service on the command line, so the fix is to provision it
- * or drop it from the selection.
- */
-export class ServiceNotOnBranchError extends Error {
-    constructor() {
-        super(...arguments);
-        this.name = "ServiceNotOnBranchError";
-    }
-}
+* Thrown when an explicit `--service` selection names a service the branch does not have.
+* Unlike the policy path — where the same situation is a {@link DevEnvMismatchError} pointing
+* at `deploy` — the user named the service on the command line, so the fix is to provision it
+* or drop it from the selection.
+*/
+var ServiceNotOnBranchError = class extends Error {
+	constructor(..._args3) {
+		super(..._args3);
+		this.name = "ServiceNotOnBranchError";
+	}
+};
 /**
- * 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
- * injects them) and `neon env pull` (which writes them to a `.env` file).
- *
- * Tiered:
- *
- *   0. {@link DevEnvContext.services} is set -> that selection *is* the policy, and any
- *      `neon.ts` is ignored. See {@link resolveSelectedServices}.
- *   1. a `neon.ts` policy is found -> the policy is the source of truth. We first
- *      check it against the branch's live state (`plan`); if it declares a resource
- *      the branch is missing, we stop with a {@link DevEnvMismatchError} pointing at
- *      `neonctl deploy`. 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
- *      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.
- *      With {@link DevEnvContext.implyAiGateway}, the AI Gateway is added on top, since
- *      `pullConfig` cannot read it back.
- *   3. otherwise -> throw {@link MissingBranchContextError}.
- *
- * Unlike {@link resolveDevEnv}, this never swallows errors — callers decide how to
- * handle them.
- */
-export const resolveNeonEnvVars = async (ctx) => {
-    if (ctx.services) {
-        return await resolveSelectedServices(ctx, ctx.services);
-    }
-    const config = await loadNeonConfig(ctx.cwd);
-    if (config) {
-        if (!ctx.projectId || !ctx.branchId) {
-            throw new MissingBranchContextError("Found a neon.ts but could not resolve the project/branch. " +
-                `Run \`${getCliName()} link\` and \`${getCliName()} checkout <branch>\`, or pass ` +
-                "--project-id / --branch.");
-        }
-        // Resolve env from the policy with its `preview.functions` removed. Functions carry no
-        // branch-level secrets — their env comes from the local `neon.ts` `functions.<slug>.env`,
-        // layered per-function by the dev server — so env resolution never needs the functions
-        // API. Probing it (via `plan`/`fetchEnv`) only adds a failure mode: an undeployed
-        // function, or a project where the Functions Preview isn't enabled, would error and sink
-        // ALL injection (including DATABASE_URL). Stripping functions keeps env resolution honest
-        // while leaving buckets / AI Gateway / Auth / Data API fully checked — those DO carry
-        // secrets, so a declared-but-missing one still hard-stops (see assertPolicyMatchesBranch).
-        const envConfig = withoutPreviewFunctions(config);
-        await assertPolicyMatchesBranch(envConfig, ctx);
-        return await fetchAndProject(envConfig, ctx);
-    }
-    if (ctx.projectId && ctx.branchId) {
-        const pulled = await pullConfig({
-            projectId: ctx.projectId,
-            branchId: ctx.branchId,
-            ...apiOptions(ctx),
-        });
-        // `pulled.config` is already a `Config` (static auth/dataApi toggles, any
-        // object-storage `preview.buckets`, and a branch tuning closure), so it feeds
-        // straight into fetchEnv — no wrapping needed. pullConfig excludes functions and
-        // the AI Gateway (neither can be faithfully read back), so fetchEnv never probes
-        // the functions API here and only mints a storage credential when a bucket exists.
-        if (!ctx.implyAiGateway) {
-            return await fetchAndProject(pulled.config, ctx);
-        }
-        return await resolveWithImpliedGateway(pulled.config, ctx, {
-            projectId: ctx.projectId,
-            branchId: ctx.branchId,
-        });
-    }
-    throw new MissingBranchContextError(`No project/branch context found. Link a branch (\`${getCliName()} link\` / ` +
-        `\`${getCliName()} checkout\`) or pass --project-id and --branch.`);
+* 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
+* injects them) and `neon env pull` (which writes them to a `.env` file).
+*
+* Tiered:
+*
+*   0. {@link DevEnvContext.services} is set -> that selection *is* the policy, and any
+*      `neon.ts` is ignored. See {@link resolveSelectedServices}.
+*   1. a `neon.ts` policy is found -> the policy is the source of truth. We first
+*      check it against the branch's live state (`plan`); if it declares a resource
+*      the branch is missing, we stop with a {@link DevEnvMismatchError} pointing at
+*      `neonctl deploy`. 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
+*      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.
+*      With {@link DevEnvContext.implyAiGateway}, the AI Gateway is added on top, since
+*      `pullConfig` cannot read it back.
+*   3. otherwise -> throw {@link MissingBranchContextError}.
+*
+* Unlike {@link resolveDevEnv}, this never swallows errors — callers decide how to
+* handle them.
+*/
+const resolveNeonEnvVars = async (ctx) => {
+	if (ctx.services) return await resolveSelectedServices(ctx, ctx.services);
+	const config = await loadNeonConfig(ctx.cwd);
+	if (config) {
+		if (!ctx.projectId || !ctx.branchId) throw new MissingBranchContextError(`Found a neon.ts but could not resolve the project/branch. Run \`${getCliName()} link\` and \`${getCliName()} checkout <branch>\`, or pass --project-id / --branch.`);
+		const envConfig = withoutPreviewFunctions(config);
+		await assertPolicyMatchesBranch(envConfig, ctx);
+		return await fetchAndProject(envConfig, ctx);
+	}
+	if (ctx.projectId && ctx.branchId) {
+		const pulled = await pullConfig({
+			projectId: ctx.projectId,
+			branchId: ctx.branchId,
+			...apiOptions(ctx)
+		});
+		if (!ctx.implyAiGateway) return await fetchAndProject(pulled.config, ctx);
+		return await resolveWithImpliedGateway(pulled.config, ctx, {
+			projectId: ctx.projectId,
+			branchId: ctx.branchId
+		});
+	}
+	throw new MissingBranchContextError(`No project/branch context found. Link a branch (\`${getCliName()} link\` / \`${getCliName()} checkout\`) or pass --project-id and --branch.`);
 };
 /** The same config with the AI Gateway enabled, leaving any other `preview` entries intact. */
 const withAiGateway = (config) => ({
-    ...config,
-    preview: { ...config.preview, aiGateway: true },
+	...config,
+	preview: {
+		...config.preview,
+		aiGateway: true
+	}
 });
 /**
- * Tier-2 resolution with the AI Gateway added on top of the branch's read-back state.
- *
- * The gateway is not detectable — `pullConfig` reports no enabled flag for it — so it is
- * implied rather than observed. Nobody named it, so it must never be the reason the whole
- * resolve fails: a project outside the regions where branch credentials exist would otherwise
- * lose its `DATABASE_URL` too, and `neon dev` would start with no env at all.
- *
- * So the gateway is only added once its credential endpoint has been shown to answer, by
- * reading the branch's credentials first. A project that does not have them says so on a
- * read, before anything is minted — which is the whole question, since the gateway's env is a
- * credential and nothing else.
- *
- * Deciding this **before** resolving, rather than by catching and retrying, is what keeps it
- * honest. A retry re-runs every call the first attempt made, so it would blame the gateway for
- * a one-off failure in shared work, and — worse — a first attempt that minted a credential and
- * then failed would be papered over by a second that succeeds without one, swallowing the
- * error and stranding a secret nobody holds. Once the read succeeds, a later failure is a real
- * failure and propagates: the same thing already happens on a branch with object storage,
- * whose credential is minted whether or not the gateway is involved.
- */
-const resolveWithImpliedGateway = async (config, ctx, 
-/** Resolved by the caller, which is the branch this env belongs to. */
-branch) => {
-    const unreachable = await credentialsUnreachable(ctx, branch);
-    if (unreachable === null) {
-        return await fetchAndProject(withAiGateway(config), ctx);
-    }
-    // Deliberately does not assert that the project lacks the gateway: a read can also fail
-    // for a reason that has nothing to do with the feature, and this is not the place to
-    // guess which. Name both, and the command that answers it.
-    log.warning("Could not reach the AI Gateway's credentials, so %s were not resolved. Everything " +
-        "else was. Either this project does not have the AI Gateway, or the call failed — " +
-        `\`${getCliName()} env pull -s ai-gateway\` will say which.\nDetails: %s`, [
-        NEON_ENV_VAR_KEYS.aiGateway.apiKey,
-        NEON_ENV_VAR_KEYS.aiGateway.baseUrl,
-    ].join(" and "), unreachable);
-    return {
-        ...(await fetchAndProject(config, ctx)),
-        skipped: ["ai-gateway"],
-    };
+* Tier-2 resolution with the AI Gateway added on top of the branch's read-back state.
+*
+* The gateway is not detectable — `pullConfig` reports no enabled flag for it — so it is
+* implied rather than observed. Nobody named it, so it must never be the reason the whole
+* resolve fails: a project outside the regions where branch credentials exist would otherwise
+* lose its `DATABASE_URL` too, and `neon dev` would start with no env at all.
+*
+* So the gateway is only added once its credential endpoint has been shown to answer, by
+* reading the branch's credentials first. A project that does not have them says so on a
+* read, before anything is minted — which is the whole question, since the gateway's env is a
+* credential and nothing else.
+*
+* Deciding this **before** resolving, rather than by catching and retrying, is what keeps it
+* honest. A retry re-runs every call the first attempt made, so it would blame the gateway for
+* a one-off failure in shared work, and — worse — a first attempt that minted a credential and
+* then failed would be papered over by a second that succeeds without one, swallowing the
+* error and stranding a secret nobody holds. Once the read succeeds, a later failure is a real
+* failure and propagates: the same thing already happens on a branch with object storage,
+* whose credential is minted whether or not the gateway is involved.
+*/
+const resolveWithImpliedGateway = async (config, ctx, branch) => {
+	const unreachable = await credentialsUnreachable(ctx, branch);
+	if (unreachable === null) return await fetchAndProject(withAiGateway(config), ctx);
+	log.warning(`Could not reach the AI Gateway's credentials, so %s were not resolved. Everything else was. Either this project does not have the AI Gateway, or the call failed — \`${getCliName()} env pull -s ai-gateway\` will say which.\nDetails: %s`, [NEON_ENV_VAR_KEYS.aiGateway.apiKey, NEON_ENV_VAR_KEYS.aiGateway.baseUrl].join(" and "), unreachable);
+	return {
+		...await fetchAndProject(config, ctx),
+		skipped: ["ai-gateway"]
+	};
 };
 /**
- * Why the branch's credentials could not be read, or `null` when they could. A plain read: it
- * mints nothing, revokes nothing, and changes nothing, so asking is free of the side effects
- * that make a failed resolve ambiguous.
- */
+* Why the branch's credentials could not be read, or `null` when they could. A plain read: it
+* mints nothing, revokes nothing, and changes nothing, so asking is free of the side effects
+* that make a failed resolve ambiguous.
+*/
 const credentialsUnreachable = async (ctx, branch) => {
-    try {
-        await apiFor(ctx).listCredentials(branch.projectId, branch.branchId);
-        return null;
-    }
-    catch (err) {
-        return err instanceof Error ? err.message : String(err);
-    }
+	try {
+		await apiFor(ctx).listCredentials(branch.projectId, branch.branchId);
+		return null;
+	} catch (err) {
+		return err instanceof Error ? err.message : String(err);
+	}
 };
 /** The adapter for direct branch reads: the injected one in tests, else built from options. */
-const apiFor = (ctx) => ctx.api ??
-    createNeonApiFromOptions("neon env", {
-        ...(ctx.apiKey ? { apiKey: ctx.apiKey } : {}),
-        ...(ctx.apiHost ? { apiHost: ctx.apiHost } : {}),
-    });
+const apiFor = (ctx) => ctx.api ?? createNeonApiFromOptions("neon env", {
+	...ctx.apiKey ? { apiKey: ctx.apiKey } : {},
+	...ctx.apiHost ? { apiHost: ctx.apiHost } : {}
+});
 /**
- * Tier-0: resolve exactly the services `--service` named, with `neon.ts` out of the picture.
- *
- * The selection is checked against the branch's live state so a service that is named but not
- * provisioned fails by name, instead of quietly contributing no vars. `postgres` and the AI
- * Gateway are not checked: every branch has Postgres, and the gateway has no branch-level
- * state to check (an unavailable one surfaces when its credential is minted).
- */
+* Tier-0: resolve exactly the services `--service` named, with `neon.ts` out of the picture.
+*
+* The selection is checked against the branch's live state so a service that is named but not
+* provisioned fails by name, instead of quietly contributing no vars. `postgres` and the AI
+* Gateway are not checked: every branch has Postgres, and the gateway has no branch-level
+* state to check (an unavailable one surfaces when its credential is minted).
+*/
 const resolveSelectedServices = async (ctx, services) => {
-    const { projectId, branchId } = ctx;
-    if (!projectId || !branchId) {
-        throw new MissingBranchContextError("--service needs a project and branch to read from. " +
-            `Run \`${getCliName()} link\` and \`${getCliName()} checkout <branch>\`, or pass ` +
-            "--project-id / --branch.");
-    }
-    // Read only the services that were named, rather than going through `pullConfig`. That
-    // keeps a selection independent of everything else on the branch — `pullConfig` also
-    // enumerates functions and credentials, so a failure there would abort `-s auth` — and it
-    // keeps an "object storage isn't available for this project" error intact, which
-    // `pullConfig` degrades to an empty bucket list and would report as "no buckets".
-    const api = apiFor(ctx);
-    const has = (service) => services.includes(service);
-    const [auth, dataApiEnabled, buckets] = await Promise.all([
-        has("auth") ? api.getNeonAuth(projectId, branchId) : null,
-        has("data-api") ? readDataApiEnabled(api, projectId, branchId) : null,
-        has("object-storage")
-            ? api.listBranchBuckets(projectId, branchId)
-            : null,
-    ]);
-    const config = configForServices(services, branchId, {
-        authEnabled: auth !== null,
-        dataApiEnabled,
-        buckets: buckets ?? [],
-    });
-    // A selection resolves part of the branch, so it must not revoke: the credential its
-    // persisted secrets name may also back a service it is not resolving. See
-    // `fetchEnvReusingSecrets`'s `revokeSuperseded`.
-    return await fetchAndProject(config, ctx, { revokeSuperseded: false });
+	const { projectId, branchId } = ctx;
+	if (!projectId || !branchId) throw new MissingBranchContextError(`--service needs a project and branch to read from. Run \`${getCliName()} link\` and \`${getCliName()} checkout <branch>\`, or pass --project-id / --branch.`);
+	const api = apiFor(ctx);
+	const has = (service) => services.includes(service);
+	const [auth, dataApiEnabled, buckets] = await Promise.all([
+		has("auth") ? api.getNeonAuth(projectId, branchId) : null,
+		has("data-api") ? readDataApiEnabled(api, projectId, branchId) : null,
+		has("object-storage") ? api.listBranchBuckets(projectId, branchId) : null
+	]);
+	const config = configForServices(services, branchId, {
+		authEnabled: auth !== null,
+		dataApiEnabled,
+		buckets: buckets ?? []
+	});
+	return await fetchAndProject(config, ctx, { revokeSuperseded: false });
 };
 /**
- * Whether the branch has a Data API integration — or `null` when that cannot be determined.
- *
- * It is enabled per branch *and database*, so this has to probe the database `fetchEnv` will
- * resolve the URL from, or the two would disagree. That is Neon's default `neondb`, else the
- * only database; several databases with no `neondb` is a case `fetchEnv` refuses to auto-pick
- * at all. Reporting "no Data API integration" there would be a claim this read cannot support,
- * so it answers `null` and lets `fetchEnv` raise its own ambiguity error, which names the
- * databases and the fix.
- */
+* Whether the branch has a Data API integration — or `null` when that cannot be determined.
+*
+* It is enabled per branch *and database*, so this has to probe the database `fetchEnv` will
+* resolve the URL from, or the two would disagree. That is Neon's default `neondb`, else the
+* only database; several databases with no `neondb` is a case `fetchEnv` refuses to auto-pick
+* at all. Reporting "no Data API integration" there would be a claim this read cannot support,
+* so it answers `null` and lets `fetchEnv` raise its own ambiguity error, which names the
+* databases and the fix.
+*/
 const readDataApiEnabled = async (api, projectId, branchId) => {
-    const databases = await api.listBranchDatabases(projectId, branchId);
-    const database = databases.find((db) => db.name === NEON_DEFAULT_DATABASE) ??
-        (databases.length === 1 ? databases[0] : undefined);
-    if (!database)
-        return databases.length === 0 ? false : null;
-    const dataApi = await api.getNeonDataApi(projectId, branchId, database.name);
-    return dataApi !== null;
+	const databases = await api.listBranchDatabases(projectId, branchId);
+	const database = databases.find((db) => db.name === NEON_DEFAULT_DATABASE) ?? (databases.length === 1 ? databases[0] : void 0);
+	if (!database) return databases.length === 0 ? false : null;
+	return await api.getNeonDataApi(projectId, branchId, database.name) !== null;
 };
 /** Neon's default database, and the one `fetchEnv` prefers when a branch has several. */
 const NEON_DEFAULT_DATABASE = "neondb";
 /**
- * Build the `Config` an explicit `--service` selection stands for, raising
- * {@link ServiceNotOnBranchError} for anything the branch does not have. Naming a service
- * that isn't there has to fail rather than contribute no vars, or a scoped pull would report
- * "no Neon env variables to pull" — which reads as a statement about the branch rather than
- * about the selection.
- */
+* Build the `Config` an explicit `--service` selection stands for, raising
+* {@link ServiceNotOnBranchError} for anything the branch does not have. Naming a service
+* that isn't there has to fail rather than contribute no vars, or a scoped pull would report
+* "no Neon env variables to pull" — which reads as a statement about the branch rather than
+* about the selection.
+*/
 const configForServices = (services, branchId, branch) => {
-    // The command that provisions each one, for a user who may well have no `neon.ts` — in
-    // which case `deploy` / `config apply` would be no help at all.
-    const provisionWith = {
-        auth: `${getCliName()} neon-auth enable`,
-        "data-api": `${getCliName()} data-api create`,
-        "object-storage": `${getCliName()} buckets create <name>`,
-    };
-    const notOnBranch = (service, what) => {
-        throw new ServiceNotOnBranchError(`--service ${service}: branch ${branchId} has no ${what}, so there are no ` +
-            `${service} env vars to pull. Provision it first (\`${provisionWith[service]}\`, ` +
-            `or in the Neon Console), or drop ${service} from --service.`);
-    };
-    const config = {};
-    if (services.includes("auth")) {
-        if (!branch.authEnabled)
-            notOnBranch("auth", "Neon Auth integration");
-        config.auth = true;
-    }
-    if (services.includes("data-api")) {
-        // Only a positive "not there" is an error; an undecidable read defers to `fetchEnv`.
-        if (branch.dataApiEnabled === false) {
-            notOnBranch("data-api", "Data API integration");
-        }
-        config.dataApi = true;
-    }
-    const preview = {};
-    if (services.includes("object-storage")) {
-        if (branch.buckets.length === 0) {
-            notOnBranch("object-storage", "object-storage buckets");
-        }
-        preview.buckets = Object.fromEntries(branch.buckets.map((bucket) => [
-            bucket.name,
-            { access: bucket.accessLevel },
-        ]));
-    }
-    if (services.includes("ai-gateway"))
-        preview.aiGateway = true;
-    if (Object.keys(preview).length > 0)
-        config.preview = preview;
-    return config;
+	const provisionWith = {
+		auth: `${getCliName()} neon-auth enable`,
+		"data-api": `${getCliName()} data-api create`,
+		"object-storage": `${getCliName()} buckets create <name>`
+	};
+	const notOnBranch = (service, what) => {
+		throw new ServiceNotOnBranchError(`--service ${service}: branch ${branchId} has no ${what}, so there are no ${service} env vars to pull. Provision it first (\`${provisionWith[service]}\`, or in the Neon Console), or drop ${service} from --service.`);
+	};
+	const config = {};
+	if (services.includes("auth")) {
+		if (!branch.authEnabled) notOnBranch("auth", "Neon Auth integration");
+		config.auth = true;
+	}
+	if (services.includes("data-api")) {
+		if (branch.dataApiEnabled === false) notOnBranch("data-api", "Data API integration");
+		config.dataApi = true;
+	}
+	const preview = {};
+	if (services.includes("object-storage")) {
+		if (branch.buckets.length === 0) notOnBranch("object-storage", "object-storage buckets");
+		preview.buckets = Object.fromEntries(branch.buckets.map((bucket) => [bucket.name, { access: bucket.accessLevel }]));
+	}
+	if (services.includes("ai-gateway")) preview.aiGateway = true;
+	if (Object.keys(preview).length > 0) config.preview = preview;
+	return config;
 };
 /**
- * `neon dev`'s env resolver: {@link resolveNeonEnvVars} with graceful degradation.
- *
- * - Success → `{ vars }` (possibly just the always-present Postgres URLs).
- * - No linked branch / project → `{ vars: {}, skipped }` with a "link a branch" hint; the
- *   function still runs locally, just without Neon env.
- * - Any other failure (offline, transient API error) → `{ vars: {}, skipped }` naming the
- *   cause; again non-fatal.
- * - {@link DevEnvMismatchError} (policy declares a secret-bearing service the branch lacks)
- *   is the one hard stop and is re-thrown for the caller to surface.
- */
-export const resolveDevEnv = async (ctx) => {
-    try {
-        const { vars, credential } = await resolveNeonEnvVars(ctx);
-        return { vars, credential };
-    }
-    catch (err) {
-        if (err instanceof DevEnvMismatchError)
-            throw err;
-        if (err instanceof MissingBranchContextError) {
-            log.debug("dev: %s; skipping env injection", err.message);
-            return {
-                vars: {},
-                skipped: {
-                    reason: `no linked Neon branch — run \`${getCliName()} link\`, then ` +
-                        `\`${getCliName()} checkout <branch>\`, to inject DATABASE_URL and friends`,
-                },
-            };
-        }
-        const detail = err instanceof Error ? err.message : String(err);
-        log.debug("dev: env resolution failed: %s", detail);
-        return {
-            vars: {},
-            skipped: {
-                reason: `could not reach Neon (${detail}); running without Neon env`,
-            },
-        };
-    }
+* `neon dev`'s env resolver: {@link resolveNeonEnvVars} with graceful degradation.
+*
+* - Success → `{ vars }` (possibly just the always-present Postgres URLs).
+* - No linked branch / project → `{ vars: {}, skipped }` with a "link a branch" hint; the
+*   function still runs locally, just without Neon env.
+* - Any other failure (offline, transient API error) → `{ vars: {}, skipped }` naming the
+*   cause; again non-fatal.
+* - {@link DevEnvMismatchError} (policy declares a secret-bearing service the branch lacks)
+*   is the one hard stop and is re-thrown for the caller to surface.
+*/
+const resolveDevEnv = async (ctx) => {
+	try {
+		const { vars, credential } = await resolveNeonEnvVars(ctx);
+		return {
+			vars,
+			credential
+		};
+	} catch (err) {
+		if (err instanceof DevEnvMismatchError) throw err;
+		if (err instanceof MissingBranchContextError) {
+			log.debug("dev: %s; skipping env injection", err.message);
+			return {
+				vars: {},
+				skipped: { reason: `no linked Neon branch — run \`${getCliName()} link\`, then \`${getCliName()} checkout <branch>\`, to inject DATABASE_URL and friends` }
+			};
+		}
+		const detail = err instanceof Error ? err.message : String(err);
+		log.debug("dev: env resolution failed: %s", detail);
+		return {
+			vars: {},
+			skipped: { reason: `could not reach Neon (${detail}); running without Neon env` }
+		};
+	}
 };
 /**
- * Return the policy with its `preview.functions` removed, so the env path never enumerates
- * functions against the Neon API. Functions are local-source-bundled and produce no
- * branch-level secrets, so they are irrelevant to env resolution; probing them only risks
- * failing the whole resolve (undeployed function, or Functions Preview disabled on the
- * project). Buckets / AI Gateway and the top-level Auth / Data API toggles are preserved —
- * they DO carry env, so they must still be checked and resolved. Returns the config
- * unchanged when it declares no functions.
- */
+* Return the policy with its `preview.functions` removed, so the env path never enumerates
+* functions against the Neon API. Functions are local-source-bundled and produce no
+* branch-level secrets, so they are irrelevant to env resolution; probing them only risks
+* failing the whole resolve (undeployed function, or Functions Preview disabled on the
+* project). Buckets / AI Gateway and the top-level Auth / Data API toggles are preserved —
+* they DO carry env, so they must still be checked and resolved. Returns the config
+* unchanged when it declares no functions.
+*/
 const withoutPreviewFunctions = (config) => {
-    const preview = config.preview;
-    if (!preview?.functions)
-        return config;
-    const previewWithoutFunctions = { ...preview };
-    delete previewWithoutFunctions.functions;
-    return { ...config, preview: previewWithoutFunctions };
+	const preview = config.preview;
+	if (!preview?.functions) return config;
+	const previewWithoutFunctions = { ...preview };
+	delete previewWithoutFunctions.functions;
+	return {
+		...config,
+		preview: previewWithoutFunctions
+	};
 };
 /**
- * Tier-1 guard. Dry-run the policy against the branch's live state and stop if
- * it declares a branch-level resource the branch is missing. Built on `plan` so
- * it covers every present and future provisionable resource for free: any
- * `create` action is a resource `neonctl deploy` would provision.
- *
- * Called with functions already stripped (see {@link withoutPreviewFunctions}), so the
- * `plan` probe never enumerates the functions API — an undeployed function, or a project
- * without the Functions Preview, must never block local dev or sink env injection.
- */
+* Tier-1 guard. Dry-run the policy against the branch's live state and stop if
+* it declares a branch-level resource the branch is missing. Built on `plan` so
+* it covers every present and future provisionable resource for free: any
+* `create` action is a resource `neonctl deploy` would provision.
+*
+* Called with functions already stripped (see {@link withoutPreviewFunctions}), so the
+* `plan` probe never enumerates the functions API — an undeployed function, or a project
+* without the Functions Preview, must never block local dev or sink env injection.
+*/
 const assertPolicyMatchesBranch = async (config, ctx) => {
-    const result = await plan(config, {
-        projectId: ctx.projectId,
-        branchId: ctx.branchId,
-        ...apiOptions(ctx),
-    });
-    const missing = result.applied.filter(isMissingResource);
-    if (missing.length === 0)
-        return;
-    const names = missing.map((change) => change.identifier).join(", ");
-    throw new DevEnvMismatchError(`Your neon.ts declares ${names} for branch ${ctx.branchId}, but the branch ` +
-        "does not have it yet, so the matching env vars cannot be injected. " +
-        `Provision it first with \`${getCliName()} deploy\` (or \`${getCliName()} config apply\`), ` +
-        `then re-run \`${getCliName()} dev\`.`);
+	const missing = (await plan(config, {
+		projectId: ctx.projectId,
+		branchId: ctx.branchId,
+		...apiOptions(ctx)
+	})).applied.filter(isMissingResource);
+	if (missing.length === 0) return;
+	throw new DevEnvMismatchError(`Your neon.ts declares ${missing.map((change) => change.identifier).join(", ")} for branch ${ctx.branchId}, but the branch does not have it yet, so the matching env vars cannot be injected. Provision it first with \`${getCliName()} deploy\` (or \`${getCliName()} config apply\`), then re-run \`${getCliName()} dev\`.`);
 };
 /**
- * A planned change that provisions a branch-level resource the branch lacks: a
- * `create` on a service (Neon Auth, Data API, a bucket, the AI Gateway). Branch
- * setting drift (`update`) and `noop`s are ignored — they don't block local dev
- * — and functions are excluded (see {@link assertPolicyMatchesBranch}).
- */
-const isMissingResource = (change) => change.kind === "service" &&
-    change.action === "create" &&
-    !change.identifier.startsWith("function:");
+* A planned change that provisions a branch-level resource the branch lacks: a
+* `create` on a service (Neon Auth, Data API, a bucket, the AI Gateway). Branch
+* setting drift (`update`) and `noop`s are ignored — they don't block local dev
+* — and functions are excluded (see {@link assertPolicyMatchesBranch}).
+*/
+const isMissingResource = (change) => change.kind === "service" && change.action === "create" && !change.identifier.startsWith("function:");
 const fetchAndProject = async (config, ctx, opts = {}) => fetchEnvReusingSecrets(config, {
-    projectId: ctx.projectId,
-    branch: ctx.branchId,
-    ...apiOptions(ctx),
-    ...(ctx.env ? { env: ctx.env } : {}),
-    ...(opts.revokeSuperseded === false ? { revokeSuperseded: false } : {}),
+	projectId: ctx.projectId,
+	branch: ctx.branchId,
+	...apiOptions(ctx),
+	...ctx.env ? { env: ctx.env } : {},
+	...opts.revokeSuperseded === false ? { revokeSuperseded: false } : {}
 });
 /**
- * Load a `neon.ts` policy if one exists on the path from `cwd` up to the repo
- * root. Returns `null` when there is none (the common "no config" case), and
- * surfaces real load errors (e.g. a syntax error in an existing file).
- */
+* Load a `neon.ts` policy if one exists on the path from `cwd` up to the repo
+* root. Returns `null` when there is none (the common "no config" case), and
+* surfaces real load errors (e.g. a syntax error in an existing file).
+*/
 /**
- * Substrings that mark a module-resolution failure while loading `neon.ts` —
- * almost always because the project's dependencies aren't installed yet (the
- * config imports `@neon/config` & friends). Deliberately specific:
- * the generic "…or a missing dependency…" hint the loader always appends is
- * NOT in here, so a real syntax/runtime error doesn't get mislabeled.
- */
+* Substrings that mark a module-resolution failure while loading `neon.ts` —
+* almost always because the project's dependencies aren't installed yet (the
+* config imports `@neon/config` & friends). Deliberately specific:
+* the generic "…or a missing dependency…" hint the loader always appends is
+* NOT in here, so a real syntax/runtime error doesn't get mislabeled.
+*/
 const MISSING_DEPENDENCY_HINTS = [
-    "cannot find module",
-    "cannot find package",
-    "err_module_not_found",
-    "failed to resolve",
-    "could not resolve",
-    "module not found",
+	"cannot find module",
+	"cannot find package",
+	"err_module_not_found",
+	"failed to resolve",
+	"could not resolve",
+	"module not found"
 ];
 /** Flatten an error and its `cause` chain to one lowercased string for matching. */
 const errorChainText = (err) => {
-    const parts = [];
-    let current = err;
-    for (let depth = 0; current instanceof Error && depth < 6; depth++) {
-        parts.push(current.message);
-        current = current.cause;
-    }
-    return parts.join("\n").toLowerCase();
+	const parts = [];
+	let current = err;
+	for (let depth = 0; current instanceof Error && depth < 6; depth++) {
+		parts.push(current.message);
+		current = current.cause;
+	}
+	return parts.join("\n").toLowerCase();
 };
 const looksLikeMissingDependency = (err) => {
-    const text = errorChainText(err);
-    return MISSING_DEPENDENCY_HINTS.some((hint) => text.includes(hint));
+	const text = errorChainText(err);
+	return MISSING_DEPENDENCY_HINTS.some((hint) => text.includes(hint));
 };
 const loadNeonConfig = async (cwd) => {
-    try {
-        const { config } = await loadConfigFromFile({ cwd });
-        return config;
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        if (/Could not find a Neon config file/i.test(message)) {
-            return null;
-        }
-        // A neon.ts that imports a package which isn't installed fails here with a
-        // cryptic "Cannot find module …". Turn that into the actionable thing to do.
-        if (looksLikeMissingDependency(err)) {
-            throw new Error("Could not load neon.ts: a package it imports is not installed. " +
-                "Did you run `npm install`? Install your dependencies " +
-                "(npm / pnpm / yarn / bun), then try again.\n" +
-                `Original error: ${message}`);
-        }
-        throw err;
-    }
+	try {
+		const { config } = await loadConfigFromFile({ cwd });
+		return config;
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		if (/Could not find a Neon config file/i.test(message)) return null;
+		if (looksLikeMissingDependency(err)) throw new Error(`Could not load neon.ts: a package it imports is not installed. Run \`${formatInstallCommand(resolvePackageManager(cwd))}\`, then try again.\nOriginal error: ${message}`);
+		throw err;
+	}
 };
+//#endregion
+export { DevEnvMismatchError, MissingBranchContextError, ServiceNotOnBranchError, resolveDevEnv, resolveNeonEnvVars };