neon 2.46.0 → 3.0.0

package/dist/dev/env.js

@@ -1,6 +1,7 @@
-import { loadConfigFromFile } from "@neon/config";
+import { createNeonApiFromOptions, loadConfigFromFile, } from "@neon/config";
 import { plan, pullConfig } from "@neon/config-runtime";
-import { fetchEnvReusingSecrets, } from "@neon/env/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";
 /** The API-targeting options every runtime call forwards from the context. */
@@ -34,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
@@ -41,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
@@ -49,12 +64,17 @@ 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) {
@@ -85,11 +105,193 @@ 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 },
+        ]));
+    }
+    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.
  *
@@ -180,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/dev/functions.js

@@ -36,8 +36,12 @@ export const resolveFunctionsFromConfig = async (cwd, branchName) => {
                 ? { port: devPort(fn.dev) }
                 : {}),
             env: { ...fn.env },
+            // Names only: locally every entry is simply left unbundled, and `includeFiles`
+            // governs the deployed archive, which `neon dev` does not build.
             ...(fn.externalPackages
-                ? { externalPackages: [...fn.externalPackages] }
+                ? {
+                    externalPackages: fn.externalPackages.map((pkg) => pkg.name),
+                }
                 : {}),
         };
     });

package/dist/env_services.js

@@ -0,0 +1,51 @@
+import { NEON_ENV_VAR_KEYS } from "./_shared/env-core/env.js";
+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/neon_services.js

@@ -0,0 +1,143 @@
+/**
+ * Every Neon service a `--service` flag can name, spelled the way a user types it — one
+ * vocabulary for the whole CLI.
+ *
+ * Kebab-case rather than the `neon.ts` field names (`aiGateway`, `buckets`) so a flag reads
+ * like a flag, and the full product name rather than a shortening (`object-storage`, not
+ * `storage`) so nothing is ambiguous when read on its own.
+ *
+ * Commands take a **subset** of this via {@link ParseServicesOptions.allowed} — `config init`
+ * can only declare what a `neon.ts` has a field for, `env pull` can only pull what produces
+ * env vars — but the spelling of a service never varies between them. The order here is the
+ * canonical one: parsing sorts into it, so a command's output never depends on the order the
+ * flags were typed in.
+ *
+ * Not to be confused with `NeonFeature` in `init/bootstrap.ts`, which is what a *template*
+ * requires. That list comes from remote manifests (`neondatabase/examples/bootstrap.yaml`),
+ * spells Postgres `database`, and is not ours to rename.
+ */
+export const NEON_SERVICES = [
+    "postgres",
+    "auth",
+    "data-api",
+    "functions",
+    "object-storage",
+    "ai-gateway",
+];
+/**
+ * Spellings that used to be canonical, and the service they now mean. Accepted so a scripted
+ * `--services storage` keeps working, warned about so it does not quietly become a second
+ * vocabulary, and absent from help text, errors, and docs so nobody learns it fresh.
+ */
+const DEPRECATED_SERVICE_ALIASES = {
+    // `config init --services storage` shipped before the vocabulary was unified.
+    storage: "object-storage",
+};
+/** An explicit empty selection, for commands where "declare nothing" is a real answer. */
+export const NO_SERVICES = "none";
+/**
+ * What to tell someone still using a retired spelling. A message rather than a log call, so
+ * the parser stays free of the CLI's writer and each command can surface it in its own voice.
+ */
+export const deprecatedServiceMessage = (used, canonical) => `"${used}" is the old name for "${canonical}" and still works, but it will be removed. ` +
+    `Use "${canonical}".`;
+/**
+ * Parse the raw values of a services flag into a canonical selection.
+ *
+ * Accepts the flag repeated (`-s auth -s postgres`) and comma-separated
+ * (`-s auth,postgres`), since both read naturally and users will try either. The result is
+ * deduplicated and sorted into {@link NEON_SERVICES} order, so what a command does never
+ * depends on typing order.
+ *
+ * An unrecognized name is rejected rather than dropped: a typo would otherwise act on
+ * everything *except* the service that was asked for, and report success. A name that is a
+ * real service but not one this command supports says so specifically — "functions has no env
+ * variables" is a different problem from a typo, and has a different fix.
+ */
+export const parseServices = (raw, options) => {
+    const { allowed, flag, noneMeans, whyUnavailable = {}, onDeprecated, } = options;
+    const supported = `Supported values: ${allowed.join(", ")}${noneMeans !== undefined ? `, ${NO_SERVICES}` : ""}.`;
+    const names = raw
+        .flatMap((value) => value.split(","))
+        .map((name) => name.trim())
+        .filter((name) => name !== "");
+    if (names.length === 0) {
+        throw new Error(`${flag} needs at least one service. ${supported}`);
+    }
+    if (noneMeans !== undefined && names.includes(NO_SERVICES)) {
+        // Deduplicate before deciding it was combined with something: a repeated value is
+        // a no-op everywhere else in this parser, so `-s none -s none` must be too.
+        if (new Set(names).size > 1) {
+            throw new Error(`${flag} ${NO_SERVICES} cannot be combined with other services.`);
+        }
+        return [];
+    }
+    // Canonicalize first and unconditionally, so a retired spelling is reported against the
+    // service it means rather than as a word nobody recognizes.
+    const deprecated = new Map();
+    const resolved = names.map((name) => {
+        const canonical = DEPRECATED_SERVICE_ALIASES[name];
+        if (canonical === undefined)
+            return name;
+        deprecated.set(name, canonical);
+        return canonical;
+    });
+    const unsupported = resolved.filter((name) => !allowed.some((service) => service === name));
+    if (unsupported.length > 0) {
+        throw new Error(`${unsupportedMessage(unsupported, flag, whyUnavailable)} ${supported}`);
+    }
+    // Warned only once the selection is valid: a run that fails validation should not also
+    // carry a "still works" claim about a value that never took effect.
+    for (const [used, canonical] of deprecated)
+        onDeprecated?.(used, canonical);
+    return NEON_SERVICES.filter((service) => allowed.includes(service) && resolved.includes(service));
+};
+/**
+ * The sentences explaining why a selection was refused. A real Neon service this command
+ * cannot act on is a different mistake from a typo — different cause, different fix — so the
+ * two are never answered with the same word, and each service carries its reason where the
+ * command supplied one.
+ */
+const unsupportedMessage = (unsupported, flag, whyUnavailable) => {
+    const known = unsupported.filter((name) => NEON_SERVICES.some((service) => service === name));
+    const unknown = unsupported.filter((name) => !known.some((service) => service === name));
+    return [
+        unknown.length > 0
+            ? `Unknown service${unknown.length === 1 ? "" : "s"} ${unknown.join(", ")}.`
+            : undefined,
+        ...known.map((service) => {
+            const why = whyUnavailable[service];
+            return `${service} is not something ${flag} can select${why ? `: ${why}` : ""}.`;
+        }),
+    ]
+        .filter((part) => part !== undefined)
+        .join(" ");
+};
+/** Every spelling of the services flag, so a habit picked up on one command works on another. */
+const SERVICE_FLAG_NAMES = ["s", "service", "services"];
+/**
+ * The yargs option for a services flag, so every command that has one accepts the same
+ * spellings (`-s`, `--service`, `--services`) and the same value syntax. `key` is the name the
+ * command reads off `argv`; the rest become aliases.
+ */
+export const servicesOption = (params) => ({
+    alias: SERVICE_FLAG_NAMES.filter((name) => name !== params.key),
+    describe: [
+        `${params.describe}: ${params.allowed.join(", ")}.`,
+        params.noneMeans !== undefined
+            ? `Pass "${NO_SERVICES}" for ${params.noneMeans}.`
+            : undefined,
+        "Repeat the flag or comma-separate.",
+        params.also,
+    ]
+        .filter((part) => part !== undefined)
+        .join(" "),
+    type: "array",
+    string: true,
+});
+/**
+ * Narrow a yargs value for a services flag to the raw strings, or `undefined` when the flag
+ * was not given. `argv` is untyped at the handler, and `string: true` only guarantees the
+ * element type when the flag was actually parsed as an array.
+ */
+export const servicesFlagValue = (value) => Array.isArray(value) ? value.map(String) : undefined;