neon 2.45.0 → 2.47.0

package/dist/commands/link.js

@@ -4,6 +4,7 @@ import { applyContext, contextBranch, readContextFile, setContext, updateContext
 import { isCi } from "../env.js";
 import { log } from "../log.js";
 import { createBranch, pickBranchInteractively, } from "../utils/branch_picker.js";
+import { getCliName } from "../utils/cli_name.js";
 import { hasNeonConfigFile, initCmd } from "./config.js";
 import { autoPullEnvAfterPin, renderAgentPullNote } from "./env.js";
 import { REGIONS } from "./projects.js";
@@ -34,7 +35,7 @@ export const builder = (argv) => argv
         alias: "branch-id",
         describe: "Branch name or ID to pin in the context (resolved to its ID before writing). " +
             "Without it, link only resolves the org and project — pin a branch with " +
-            "`neonctl checkout <branch>` (link never guesses a default).",
+            `\`${getCliName()} checkout <branch>\` (link never guesses a default).`,
         type: "string",
     },
     params: {
@@ -76,7 +77,7 @@ export const builder = (argv) => argv
     .example([
     [
         "$0 link --project-id polished-snowflake-12345678",
-        "Link an existing project (org is inferred); pin a branch later with 'neonctl checkout'",
+        `Link an existing project (org is inferred); pin a branch later with '${getCliName()} checkout'`,
     ],
     [
         "$0 link --org-id org-… --project-name my-app --region-id aws-us-east-2",
@@ -120,9 +121,9 @@ export const handler = async (props) => {
             "Missing inputs and CI environment detected (no TTY for prompts).",
             "",
             "Use one of:",
-            "  neonctl link --agent                                                    (JSON state machine for agents)",
-            "  neonctl link --project-id <project>                                     (link to an existing project; org is inferred)",
-            "  neonctl link --org-id <org> --project-name <name> --region-id <region>  (create a new project and link)",
+            `  ${getCliName()} link --agent                                                    (JSON state machine for agents)`,
+            `  ${getCliName()} link --project-id <project>                                     (link to an existing project; org is inferred)`,
+            `  ${getCliName()} link --org-id <org> --project-name <name> --region-id <region>  (create a new project and link)`,
         ].join("\n"));
         process.exit(1);
         return;
@@ -180,7 +181,7 @@ const validateInputs = (inputs) => {
         throw new Error("Conflicting inputs: --project-id selects an existing project; --project-name and --region-id describe a new one. Pass only one set.");
     }
     if (inputs.projectName && inputs.branch) {
-        throw new Error("Conflicting inputs: --branch pins a branch of an existing project, but --project-name creates a new one. Create the project first, then `neonctl checkout <branch>`.");
+        throw new Error(`Conflicting inputs: --branch pins a branch of an existing project, but --project-name creates a new one. Create the project first, then \`${getCliName()} checkout <branch>\`.`);
     }
 };
 /**
@@ -338,7 +339,7 @@ const resolveBranchRef = async (props, projectId, branchRef) => {
             .map((b) => `${b.id}${b.name ? ` (${b.name})` : ""}`)
             .join(", ")
         : "(none)";
-    throw new LinkInputError(`Branch '${branchRef}' not found in project '${projectId}'. Available branches: ${available}. Pin one with \`neonctl checkout <branch>\`.`, "NOT_FOUND");
+    throw new LinkInputError(`Branch '${branchRef}' not found in project '${projectId}'. Available branches: ${available}. Pin one with \`${getCliName()} checkout <branch>\`.`, "NOT_FOUND");
 };
 /**
  * The value to persist for a branch: prefer its human-readable **name** (nicer
@@ -717,7 +718,7 @@ const runAgent = async (props, inputs) => {
             context_file: props.contextFile,
             context: { orgId, projectId },
             project: { id: projectId },
-            message: `Linked ${props.contextFile} to project ${projectId}${orgSuffix}. No branch pinned — run \`neonctl checkout <branch>\` (omit the branch to list options) to pin one and pull its env vars.`,
+            message: `Linked ${props.contextFile} to project ${projectId}${orgSuffix}. No branch pinned — run \`${getCliName()} checkout <branch>\` (omit the branch to list options) to pin one and pull its env vars.`,
         });
         return;
     }
@@ -737,7 +738,7 @@ const runAgent = async (props, inputs) => {
                 name: region.name,
                 default: region.default,
             })),
-            next_command_template: `neonctl link --agent --org-id ${shellArg(orgId)} --project-name ${shellArg(projectName)} --region-id <region_id>`,
+            next_command_template: `${getCliName()} link --agent --org-id ${shellArg(orgId)} --project-name ${shellArg(projectName)} --region-id <region_id>`,
         });
         return;
     }
@@ -781,7 +782,7 @@ const runAgent = async (props, inputs) => {
     // the instruction rather than silently dropped.
     const projects = await listAllProjects(props, orgId);
     const branchNote = branch
-        ? ` A branch was requested (--branch ${branch}) but a branch can only be pinned once a project is chosen — re-run with --project-id first, then \`neonctl checkout ${branch}\`.`
+        ? ` A branch was requested (--branch ${branch}) but a branch can only be pinned once a project is chosen — re-run with --project-id first, then \`${getCliName()} checkout ${branch}\`.`
         : "";
     emitAgent({
         status: "needs_project",
@@ -796,9 +797,9 @@ const runAgent = async (props, inputs) => {
         })),
         create_option: {
             instruction: "To create a new project, ask the user for a project name. The region can be omitted to receive a follow-up needs_project_details response that lists available regions.",
-            next_command_template: `neonctl link --agent --org-id ${shellArg(orgId)} --project-name <name> --region-id <region_id>`,
+            next_command_template: `${getCliName()} link --agent --org-id ${shellArg(orgId)} --project-name <name> --region-id <region_id>`,
         },
-        next_command_template: `neonctl link --agent --org-id ${shellArg(orgId)} --project-id <project_id>`,
+        next_command_template: `${getCliName()} link --agent --org-id ${shellArg(orgId)} --project-id <project_id>`,
     });
 };
 const emitAgent = (response) => {
@@ -865,7 +866,7 @@ const buildNeedsOrgResponse = (resolution) => {
             status: "needs_org",
             instruction: "This Neon API key is organization-scoped, so the CLI cannot list the user's organizations and no existing project was found to auto-detect the org ID. Ask the user for their Neon organization ID (visible in the Neon Console under the org's Settings page, formatted like `org-bitter-breeze-12345678`) and re-run the next_command_template with that --org-id.",
             options: [],
-            next_command_template: "neonctl link --agent --org-id <org_id>",
+            next_command_template: `${getCliName()} link --agent --org-id <org_id>`,
         };
     }
     const orgs = resolution.orgs;
@@ -875,7 +876,7 @@ const buildNeedsOrgResponse = (resolution) => {
             ? "The user does not belong to any organizations. Ask them to create one in the Neon Console (https://console.neon.tech/) before linking."
             : `Ask the user which of these ${orgs.length} organization${orgs.length === 1 ? "" : "s"} they want to link the current directory to. After they pick one, re-run the next_command_template with the chosen --org-id value.`,
         options: orgs.map((org) => ({ id: org.id, name: org.name })),
-        next_command_template: "neonctl link --agent --org-id <org_id>",
+        next_command_template: `${getCliName()} link --agent --org-id <org_id>`,
     };
 };
 const toAgentError = (err) => {
@@ -954,7 +955,7 @@ const resolveInteractiveBranch = async (props, projectId) => {
     const picked = await pickBranchInteractively(branches, {
         message: "Which branch would you like to link?",
         nonInteractiveMessage: "No branch could be selected without an interactive terminal. " +
-            "Re-run `neonctl link` interactively, or `neonctl checkout <branch>` to pin one.",
+            `Re-run \`${getCliName()} link\` interactively, or \`${getCliName()} checkout <branch>\` to pin one.`,
     });
     if (picked.kind === "existing") {
         const existing = branches.find((b) => b.id === picked.branchId);
@@ -1031,7 +1032,7 @@ const printSummary = (_props, summary) => {
     }
     else if (summary.projectId && !summary.branch && !summary.orgOnly) {
         lines.push("");
-        lines.push("No branch pinned. Run `neonctl checkout <branch>` to pin a branch and pull its env vars.");
+        lines.push(`No branch pinned. Run \`${getCliName()} checkout <branch>\` to pin a branch and pull its env vars.`);
     }
     lines.push("");
     process.stdout.write(`${lines.join("\n")}\n`);

package/dist/commands/projects.js

@@ -4,6 +4,7 @@ import { updateContextFile } from "../context.js";
 import { isCi } from "../env.js";
 import { log } from "../log.js";
 import { projectCreateRequest, projectUpdateRequest, } from "../parameters.gen.js";
+import { getCliName } from "../utils/cli_name.js";
 import { getComputeUnits } from "../utils/compute_units.js";
 import { psql } from "../utils/psql.js";
 import { writer } from "../writer.js";
@@ -392,11 +393,11 @@ The organization ID has been saved in ${props.contextFile}
 
 If you'd like to change the default organization later, use
 
-    neonctl link --org-id <org_id>
+    ${getCliName()} link --org-id <org_id>
 
 Or to clear the context file and forget the default organization
 
-    neonctl link --clear
+    ${getCliName()} link --clear
 
 `);
     }

package/dist/commands/set_context.js

@@ -1,7 +1,8 @@
 import { applyContext } from "../context.js";
 import { log } from "../log.js";
+import { getCliName } from "../utils/cli_name.js";
 export const command = "set-context";
-export const describe = "Deprecated: use `neonctl link`. Set the .neon context (raw write).";
+export const describe = `Deprecated: use \`${getCliName()} link\`. Set the .neon context (raw write).`;
 export const builder = (argv) => argv.usage("$0 set-context [options]").options({
     "project-id": {
         describe: "Project ID",
@@ -17,9 +18,9 @@ export const builder = (argv) => argv.usage("$0 set-context [options]").options(
     },
 });
 export const handler = (props) => {
-    log.warning("`neonctl set-context` is deprecated and will be removed in a future release. " +
-        "Use `neonctl link` instead — it verifies inputs and infers the org for you " +
-        "(or `neonctl link --no-checks` for the same write-without-checks behavior).");
+    log.warning(`\`${getCliName()} set-context\` is deprecated and will be removed in a future release. ` +
+        `Use \`${getCliName()} link\` instead — it verifies inputs and infers the org for you ` +
+        `(or \`${getCliName()} link --no-checks\` for the same write-without-checks behavior).`);
     const context = {
         projectId: props.projectId,
         orgId: props.orgId,

package/dist/config_template.js

@@ -1,3 +1,4 @@
+import { NEON_SERVICES } from "./neon_services.js";
 /**
  * The published npm packages a `neon.ts` project needs — the `@neon/*` org names.
  *
@@ -11,55 +12,32 @@ export const CONFIG_PACKAGE = "@neon/config";
 export const ENV_PACKAGE = "@neon/env";
 export const REQUIRED_PACKAGES = [CONFIG_PACKAGE, ENV_PACKAGE];
 /**
- * A Neon service `config init` can declare in the `neon.ts` it scaffolds, spelled the way a
- * user types it in `--services`. Kebab-case rather than the `neon.ts` field names (`aiGateway`,
- * `buckets`) so the flag reads like a flag; {@link renderNeonConfig} owns the mapping.
+ * The services `config init` can declare in the `neon.ts` it scaffolds — the subset of
+ * {@link NEON_SERVICES} a policy has a field for. {@link renderNeonConfig} owns the mapping
+ * from these names to the `neon.ts` fields (`aiGateway`, `buckets`).
  *
- * Postgres is absent because every branch has it, and `dataApi` is absent because enabling it
- * with the default `authProvider: "neon"` requires `auth` — a pairing the picker would have to
- * enforce rather than offer.
+ * Postgres is absent because every branch has it, so there is nothing to declare. `data-api`
+ * is absent because enabling it with the default `authProvider: "neon"` requires `auth` — a
+ * pairing the picker would have to enforce rather than offer.
  */
-export const NEON_SERVICES = [
-    "auth",
-    "functions",
-    "storage",
-    "ai-gateway",
-];
-/** `--services none`: declare nothing, i.e. scaffold the bare starter policy. */
-export const NO_SERVICES = "none";
+export const CONFIG_INIT_SERVICES = NEON_SERVICES.filter((service) => service !== "postgres" && service !== "data-api");
+/**
+ * What `config init --services none` produces. One constant because it is both the help text
+ * and what tells the parser `none` is a value here — passing the literal at each call site
+ * lets the two drift into documenting something the parser does not accept.
+ */
+export const CONFIG_INIT_NONE_MEANS = "the bare starter policy";
+/** Why the two a policy cannot declare are not selectable, for the refusal message. */
+export const CONFIG_INIT_UNAVAILABLE = {
+    postgres: "every branch has Postgres, so a policy has nothing to declare for it",
+    "data-api": "enabling it with the default provider requires auth, so declare auth here and turn the Data API on with `neon data-api create`",
+};
 /** Slug, display name, and source path of the function scaffolded for `functions`. */
 export const FUNCTION_SLUG = "hello";
 export const FUNCTION_NAME = "Hello World";
 export const FUNCTION_FILENAME = "hello.ts";
 /** Name of the bucket scaffolded for `storage`. */
 export const BUCKET_NAME = "assets";
-/**
- * Parse a `--services` value into a canonical service list: comma-separated
- * {@link NEON_SERVICES} names, or {@link NO_SERVICES} on its own for none.
- *
- * Unknown names are rejected here rather than silently dropped — a typo'd service would
- * otherwise scaffold a policy missing exactly the service the user asked for. The result is
- * deduplicated and ordered by {@link NEON_SERVICES} so the rendered file doesn't depend on the
- * order they were typed in.
- */
-export const parseServices = (raw) => {
-    const names = raw
-        .split(",")
-        .map((name) => name.trim())
-        .filter((name) => name !== "");
-    if (names.includes(NO_SERVICES)) {
-        if (names.length > 1) {
-            throw new Error(`--services ${NO_SERVICES} cannot be combined with other services.`);
-        }
-        return [];
-    }
-    const unknown = names.filter((name) => !NEON_SERVICES.includes(name));
-    if (unknown.length > 0) {
-        throw new Error(`Unknown service${unknown.length === 1 ? "" : "s"} ${unknown.join(", ")}. ` +
-            `Supported values: ${NEON_SERVICES.join(", ")}, ${NO_SERVICES}.`);
-    }
-    return NEON_SERVICES.filter((service) => names.includes(service));
-};
 /**
  * One indentation level in the emitted `neon.ts`. Two spaces, which is what every renderer
  * here produces and what `config_template.format.test.ts` holds them to.
@@ -88,7 +66,7 @@ const renderPreview = (services) => {
             ...at(3, `${FUNCTION_SLUG}: { name: "${FUNCTION_NAME}", source: "./${FUNCTION_FILENAME}" },`),
         ]));
     }
-    if (services.includes("storage")) {
+    if (services.includes("object-storage")) {
         lines.push(...block(2, "buckets", [
             ...at(3, `// "private" is the default; use "public_read" for anonymous reads`, `${BUCKET_NAME}: { access: "private" },`),
         ]));

package/dist/current_branch_fast_path.js

@@ -1,5 +1,6 @@
 import { contextBranch, currentContextFile, readContextFile, } from "./context.js";
 import { log } from "./log.js";
+import { getCliName } from "./utils/cli_name.js";
 /**
  * Offline fast path for `(config) status --current-branch` (used by shell prompts).
  *
@@ -35,7 +36,7 @@ cwd = process.cwd()) => {
         process.stdout.write(`${branch}\n`);
     }
     else {
-        log.info("No branch pinned. Run `neonctl checkout <branch>` to pin a branch and pull its env vars.");
+        log.info(`No branch pinned. Run \`${getCliName()} checkout <branch>\` to pin a branch and pull its env vars.`);
         process.exitCode = 1;
     }
     return true;

package/dist/dev/env.js

@@ -1,7 +1,9 @@
-import { loadConfigFromFile } from "@neon/config";
+import { createNeonApiFromOptions, loadConfigFromFile, } from "@neon/config";
 import { plan, pullConfig } from "@neon/config-runtime";
+import { NEON_ENV_VAR_KEYS } from "@neon/env";
 import { fetchEnvReusingSecrets, } from "@neon/env/runtime";
 import { log } from "../log.js";
+import { getCliName } from "../utils/cli_name.js";
 /** The API-targeting options every runtime call forwards from the context. */
 const apiOptions = (ctx) => ({
     ...(ctx.apiKey ? { apiKey: ctx.apiKey } : {}),
@@ -33,6 +35,18 @@ export class MissingBranchContextError extends Error {
         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";
+    }
+}
 /**
  * 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
@@ -40,6 +54,8 @@ export class MissingBranchContextError extends Error {
  *
  * 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
@@ -48,17 +64,22 @@ export class MissingBranchContextError extends Error {
  *      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 `neonctl link` and `neonctl checkout <branch>`, or pass " +
+                `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
@@ -84,10 +105,192 @@ export const resolveNeonEnvVars = async (ctx) => {
         // 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.
-        return await fetchAndProject(pulled.config, 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 },
+});
+/**
+ * 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"],
+    };
+};
+/**
+ * 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);
+    }
+};
+/** 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 } : {}),
+    });
+/**
+ * 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 });
+};
+/**
+ * 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;
+};
+/** 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.
+ */
+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 },
+        ]));
     }
-    throw new MissingBranchContextError("No project/branch context found. Link a branch (`neonctl link` / " +
-        "`neonctl checkout`) or pass --project-id and --branch.");
+    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.
@@ -113,8 +316,8 @@ export const resolveDevEnv = async (ctx) => {
             return {
                 vars: {},
                 skipped: {
-                    reason: "no linked Neon branch — run `neonctl link`, then " +
-                        "`neonctl checkout <branch>`, to inject DATABASE_URL and friends",
+                    reason: `no linked Neon branch — run \`${getCliName()} link\`, then ` +
+                        `\`${getCliName()} checkout <branch>\`, to inject DATABASE_URL and friends`,
                 },
             };
         }
@@ -167,8 +370,8 @@ const assertPolicyMatchesBranch = async (config, ctx) => {
     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 `neonctl deploy` (or `neonctl config apply`), " +
-        "then re-run `neonctl dev`.");
+        `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
@@ -179,11 +382,12 @@ const assertPolicyMatchesBranch = async (config, ctx) => {
 const isMissingResource = (change) => change.kind === "service" &&
     change.action === "create" &&
     !change.identifier.startsWith("function:");
-const fetchAndProject = async (config, ctx) => fetchEnvReusingSecrets(config, {
+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 } : {}),
 });
 /**
  * Load a `neon.ts` policy if one exists on the path from `cwd` up to the repo

package/dist/env_services.js

@@ -0,0 +1,51 @@
+import { NEON_ENV_VAR_KEYS } from "@neon/env";
+import { NEON_SERVICES } from "./neon_services.js";
+/**
+ * The services `env pull --service` can select: every Neon service that produces branch env
+ * vars. `functions` is the one left out — a function's env comes from the local `neon.ts`,
+ * never from the branch, so there is nothing to pull.
+ */
+export const ENV_PULL_SERVICES = NEON_SERVICES.filter((service) => service !== "functions");
+/** Why the services `env pull` leaves out are not selectable, for the refusal message. */
+export const ENV_PULL_UNAVAILABLE = {
+    functions: "a function's env comes from your neon.ts, not from the branch, so there is nothing to pull",
+};
+/** The OS-level env vars each service contributes to a pulled `.env`. */
+const SERVICE_ENV_KEYS = {
+    postgres: Object.values(NEON_ENV_VAR_KEYS.postgres),
+    auth: Object.values(NEON_ENV_VAR_KEYS.auth),
+    "data-api": Object.values(NEON_ENV_VAR_KEYS.dataApi),
+    "object-storage": Object.values(NEON_ENV_VAR_KEYS.storage),
+    "ai-gateway": Object.values(NEON_ENV_VAR_KEYS.aiGateway),
+    functions: [],
+};
+/**
+ * The subset of {@link SERVICE_ENV_KEYS} a pull *owns*, and so may prune from the target file
+ * when the branch no longer has it. Object storage is deliberately absent: it is emitted under
+ * the third-party `AWS_*` names, which collide with credentials a user may set by hand, so
+ * `env pull` only ever writes them.
+ */
+const SERVICE_OWNED_ENV_KEYS = {
+    ...SERVICE_ENV_KEYS,
+    "object-storage": [],
+};
+/**
+ * Branch identity. Not a service — every branch has a name — so a scoped pull refreshes it
+ * alongside whatever services were selected.
+ */
+export const BRANCH_ENV_KEY = NEON_ENV_VAR_KEYS.branch.name;
+/** Every env var the selected services contribute, plus branch identity. */
+export const envServiceKeys = (services) => {
+    const keys = new Set([BRANCH_ENV_KEY]);
+    for (const service of services) {
+        for (const key of SERVICE_ENV_KEYS[service])
+            keys.add(key);
+    }
+    return keys;
+};
+/**
+ * The env vars a pull scoped to `services` may prune. Narrower than the unscoped set on
+ * purpose: `env pull -s ai-gateway` says nothing about `DATABASE_URL`, so it must leave it
+ * alone rather than treat its absence from this pull as "the branch no longer has it".
+ */
+export const ownedEnvServiceKeys = (services) => services.flatMap((service) => SERVICE_OWNED_ENV_KEYS[service]);

package/dist/index.js

@@ -1,4 +1,3 @@
-import { basename } from "node:path";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 import { analyticsMiddleware, closeAnalytics, getAnalyticsEventProperties, initAnalyticsClientMiddleware, sendError, trackEvent, } from "./analytics.js";
@@ -13,6 +12,7 @@ import { isNetworkError, matchErrorCode, NETWORK_ERROR_MESSAGE, } from "./errors
 import { showHelp } from "./help.js";
 import { log } from "./log.js";
 import pkg from "./pkg.js";
+import { getCliName } from "./utils/cli_name.js";
 import { fillInArgs, resolveApiKeyFromEnv } from "./utils/middlewares.js";
 const NO_SUBCOMMANDS_VERBS = [
     // `api <path>` has a handler but no subcommands (like `status`), so the
@@ -159,7 +159,7 @@ builder = builder
     .group("version", "Global options:")
     .alias("version", "v")
     .completion()
-    .scriptName(basename(process.argv[1]) === "neon" ? "neon" : "neonctl")
+    .scriptName(getCliName())
     .epilog("For more information, visit https://neon.com/docs/reference/neon-cli")
     .wrap(null)
     .fail(false);