neonctl 2.32.0 → 2.33.1

package/dist/commands/config.js

@@ -3,11 +3,13 @@ import { join } from "node:path";
 import { resolveConfig } from "@neon/config";
 import { apply, createBranch as createBranchFromPolicy, inspect, loadConfigFromFile, PushConflictError, plan, } from "@neon/config-runtime";
 import chalk from "chalk";
+import { getApiClient } from "../api.js";
 import { toNeonConfigView } from "../config_format.js";
 import { contextBranch, readContextFile } from "../context.js";
 import { isCi } from "../env.js";
 import { loadEnvFileIntoProcess } from "../env_file.js";
 import { log } from "../log.js";
+import { assertAiGatewayProvisionable, warnAiGateway, } from "../utils/ai_gateway_notice.js";
 import { announceTargetBranch } from "../utils/branch_notice.js";
 import { renderAppliedChanges, renderBranchSettingConflicts, } from "../utils/config_diff.js";
 import { fillSingleProject, resolveBranchRef } from "../utils/enrichers.js";
@@ -311,13 +313,33 @@ export const planCmd = async (props) => {
         ...(props.apiHost ? { apiHost: props.apiHost } : {}),
         ...(props.runtimeApi ? { api: props.runtimeApi } : {}),
     });
-    reportPushResult(props, result, "plan", utilizedServices(config));
+    const services = utilizedServices(config);
+    reportPushResult(props, result, "plan", services);
+    // `plan` is a dry run and never pulls credentials, so it can only offer the plan-based
+    // (Free) AI Gateway notice — the reduced-model-set check needs a live gateway token,
+    // which `apply`/`checkout`/`env pull` get via the bundled env pull. Best-effort.
+    if (services.includes("AI Gateway")) {
+        await warnAiGateway({
+            apiClient: props.apiClient,
+            projectId: props.projectId,
+            branchId,
+        });
+    }
 };
 export const applyCmd = async (props) => {
     const config = await loadConfig(props);
     const branch = await resolveBranchRef(props);
     announceTargetBranch(props, branch, "Applying to branch");
     const branchId = branch.branchId;
+    // The AI Gateway can't serve on the Free plan, so refuse to provision it up front rather
+    // than write a credential that won't work. Only when the policy actually enables the
+    // gateway; best-effort on the plan lookup (a transient failure never blocks a paid user).
+    if (utilizedServices(config).includes("AI Gateway")) {
+        await assertAiGatewayProvisionable({
+            apiClient: props.apiClient,
+            projectId: props.projectId,
+        });
+    }
     let result;
     try {
         result = await apply(config, {
@@ -466,6 +488,26 @@ const reportConflicts = (props, conflicts) => {
         }
     }
 };
+/**
+ * Block provisioning the AI Gateway on a Free plan from the `checkout` policy paths, which
+ * carry raw credentials (`apiKey`/`apiHost`) rather than the CLI's api client. Builds a client
+ * from them and defers to {@link assertAiGatewayProvisionable}. Skipped when a `runtimeApi` is
+ * injected (tests) or no `apiKey` is available; the interactive commands always have a key.
+ */
+const assertAiGatewayProvisionableFromCreds = async (props) => {
+    if (props.runtimeApi || !props.apiKey)
+        return;
+    if (!utilizedServices(props.config).includes("AI Gateway"))
+        return;
+    const apiClient = getApiClient({
+        apiKey: props.apiKey,
+        ...(props.apiHost ? { apiHost: props.apiHost } : {}),
+    });
+    await assertAiGatewayProvisionable({
+        apiClient,
+        projectId: props.projectId,
+    });
+};
 /**
  * Apply a `neon.ts` policy to a **freshly created** branch (used by `neonctl checkout`
  * when it creates a branch). No-op when there is no `neon.ts` on the path from cwd up to
@@ -488,6 +530,13 @@ export const applyPolicyOnCreate = async (props) => {
             return;
         throw err;
     }
+    await assertAiGatewayProvisionableFromCreds({
+        projectId: props.projectId,
+        ...(props.apiKey ? { apiKey: props.apiKey } : {}),
+        ...(props.apiHost ? { apiHost: props.apiHost } : {}),
+        ...(props.runtimeApi ? { runtimeApi: props.runtimeApi } : {}),
+        config,
+    });
     log.info("Applying neon.ts policy to the new branch…");
     const result = await apply(config, {
         projectId: props.projectId,
@@ -535,6 +584,13 @@ export const createBranchFromPolicyOnCheckout = async (props) => {
             return null;
         throw err;
     }
+    await assertAiGatewayProvisionableFromCreds({
+        projectId: props.projectId,
+        ...(props.apiKey ? { apiKey: props.apiKey } : {}),
+        ...(props.apiHost ? { apiHost: props.apiHost } : {}),
+        ...(props.runtimeApi ? { runtimeApi: props.runtimeApi } : {}),
+        config,
+    });
     const { branchId, branchName, result } = await createBranchFromPolicy(config, {
         projectId: props.projectId,
         branchName: props.branchName,

package/dist/commands/env.js

@@ -4,6 +4,7 @@ import chalk from "chalk";
 import { resolveNeonEnvVars } from "../dev/env.js";
 import { mergeEnvFile, readEnvFile, resolveEnvFilePath } from "../env_file.js";
 import { log } from "../log.js";
+import { warnAiGateway } from "../utils/ai_gateway_notice.js";
 import { announceTargetBranch } from "../utils/branch_notice.js";
 import { fillSingleProject, resolveBranchRef } from "../utils/enrichers.js";
 export const command = "env";
@@ -104,6 +105,20 @@ export const pull = async (props, opts = {}) => {
     if (removed.length > 0) {
         log.info("Removed %d stale Neon variable%s not enabled on this branch: %s", removed.length, removed.length === 1 ? "" : "s", removed.join(", "));
     }
+    // When the branch has the AI Gateway enabled, the pulled credentials always work, but
+    // serving is plan-gated and the model set can be reduced on the beta — surface that as a
+    // courtesy notice (best-effort; never fails the pull). The freshly pulled token lets us
+    // probe the branch's own /v1/models to detect a reduced catalog.
+    const gatewayBaseUrl = neonVars.NEON_AI_GATEWAY_BASE_URL;
+    const gatewayToken = neonVars.NEON_AI_GATEWAY_TOKEN;
+    if (gatewayBaseUrl && gatewayToken) {
+        await warnAiGateway({
+            apiClient: props.apiClient,
+            projectId: props.projectId,
+            branchId,
+            gateway: { baseUrl: gatewayBaseUrl, token: gatewayToken },
+        });
+    }
     return { status: "written", written, file: targetPath };
 };
 /**

package/dist/utils/ai_gateway_notice.js

@@ -0,0 +1,173 @@
+import { log } from "../log.js";
+/**
+ * Friendly guidance shown when a branch enables the AI Gateway (`preview.aiGateway`).
+ *
+ * The gateway is credential-gated, not provisioned: enabling it always mints a working
+ * branch credential, so `apply` / `checkout` / `env pull` succeed regardless of plan. The
+ * two things that *do* gate the gateway happen at serving time and are invisible in the
+ * provisioning result, so we surface them as a courtesy notice instead:
+ *
+ *  - **Free plan** — credentials provision, but the gateway does not *serve* model requests.
+ *    The account needs to upgrade to a paid plan.
+ *  - **Reduced model set** — on a paid plan, an account still ramping up on the beta gets a
+ *    trimmed model catalog (flagship models are missing from `/v1/models`). They can request
+ *    access to more models.
+ *
+ * This is deliberately phrased for the user: it never mentions account "verification" or any
+ * other internal gating mechanism.
+ */
+/**
+ * `BillingSubscriptionType` values that mean the account is on a Free plan (the gateway
+ * won't serve requests). Everything else — `launch`, `scale`, `business`, the `*_v3`
+ * variants, marketplace plans — is treated as paid.
+ */
+const FREE_SUBSCRIPTION_TYPES = new Set(["free_v2", "free_v3"]);
+/**
+ * The Neon Console billing page to upgrade a Free-plan account so the gateway can serve. It's
+ * org-scoped when the project belongs to an org; projects on a personal account (which is
+ * where Free plans usually live) have no org id, so we fall back to the account-level page.
+ */
+export const aiGatewayUpgradeUrl = (orgId) => orgId
+    ? `https://console.neon.tech/app/${orgId}/billing`
+    : "https://console.neon.tech/app/billing";
+/**
+ * The branch's AI Gateway page in the Neon Console — where a paid user with a reduced model
+ * set requests access to more models. It's branch-scoped, so it's built from the linked
+ * project and branch ids.
+ */
+export const aiGatewayModelsUrl = (projectId, branchId) => `https://console.neon.tech/app/projects/${projectId}/branches/${branchId}/ai-gateway`;
+export const isFreePlan = (subscriptionType) => subscriptionType !== undefined &&
+    FREE_SUBSCRIPTION_TYPES.has(subscriptionType);
+/**
+ * Whether a model catalog includes at least one flagship model. Flagship models (Anthropic
+ * Opus, OpenAI Codex / `*-pro`) are the first to be held back for an account still ramping
+ * up on the beta, so their total absence from a non-empty catalog is the signal that the
+ * account has a reduced model set. Matched by id substring so it survives model version
+ * bumps (e.g. `claude-opus-4-8`).
+ */
+export const hasFlagshipModels = (modelIds) => modelIds.some((id) => id.includes("opus") || id.includes("codex") || id.endsWith("-pro"));
+/**
+ * The message shown when a `neon.ts` that enables the AI Gateway is applied on a Free plan.
+ * Provisioning is refused up front (see {@link assertAiGatewayProvisionable}) because the
+ * gateway won't serve model requests until the account is on a paid plan. `upgradeUrl` is the
+ * org-scoped Console billing page (see {@link aiGatewayUpgradeUrl}).
+ */
+export const freePlanBlockMessage = (upgradeUrl) => "This neon.ts enables the AI Gateway, which isn't available on the Free plan — the " +
+    "gateway won't serve model requests. Upgrade to a paid plan and re-run, or remove " +
+    `\`preview.aiGateway\` from neon.ts. Upgrade here: ${upgradeUrl}`;
+/**
+ * Build the AI Gateway courtesy notice for an account's plan and (optionally) its live model
+ * catalog, or `null` when nothing needs saying.
+ *
+ * `modelIds` is `undefined` when the catalog wasn't probed (e.g. a dry-run `plan`, or a probe
+ * that failed); in that case only the plan-based (Free) notice can be produced — never a
+ * false "reduced models" warning. `upgradeUrl` is the org-scoped Console billing page
+ * (Free notice); `moreModelsUrl` is the branch's Console AI Gateway page
+ * (see {@link aiGatewayModelsUrl}), shown when the catalog is reduced.
+ */
+export const buildAiGatewayNotice = ({ subscriptionType, modelIds, upgradeUrl, moreModelsUrl, }) => {
+    if (isFreePlan(subscriptionType)) {
+        return {
+            level: "warning",
+            message: "AI Gateway is enabled, but the gateway does not serve model requests on the " +
+                `Free plan. Upgrade to a paid plan to start making requests: ${upgradeUrl}`,
+        };
+    }
+    if (modelIds !== undefined &&
+        modelIds.length > 0 &&
+        !hasFlagshipModels(modelIds)) {
+        return {
+            level: "warning",
+            message: "AI Gateway is in public beta and not every model is enabled for your account " +
+                "yet, so some models are missing from the catalog. Request access to more " +
+                `models here: ${moreModelsUrl}`,
+        };
+    }
+    return null;
+};
+const isRecord = (value) => typeof value === "object" && value !== null;
+/** Pull the string `id`s out of an OpenAI-compatible `{ object: "list", data: [...] }` body. */
+const extractModelIds = (body) => {
+    if (!isRecord(body) || !Array.isArray(body.data))
+        return null;
+    const ids = [];
+    for (const entry of body.data) {
+        if (isRecord(entry) && typeof entry.id === "string") {
+            ids.push(entry.id);
+        }
+    }
+    return ids;
+};
+/**
+ * `GET {baseUrl}/v1/models` → the served model ids, or `null` if the catalog can't be read
+ * (network / HTTP / parse failure). Returning `null` keeps the notice silent rather than
+ * risking a false "reduced models" warning. `/v1/models` is served only on the unified
+ * dialect (the `/openai/v1` Responses dialect returns 404).
+ */
+export const fetchGatewayModelIds = async (baseUrl, token) => {
+    try {
+        const res = await fetch(`${baseUrl.replace(/\/+$/, "")}/v1/models`, {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (!res.ok)
+            return null;
+        return extractModelIds(await res.json());
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Refuse to provision the AI Gateway on a Free plan. Called before the `neon.ts` lifecycle
+ * commands provision a branch (`config apply` / `deploy`, `checkout`), so a Free-plan user
+ * gets a clear "upgrade first" error instead of a credential that can't serve requests.
+ *
+ * Best-effort on the plan lookup: if the plan can't be determined (network / API failure) we
+ * do NOT block, so a transient error never wrongly refuses a paid user's deploy. Only a
+ * positively-identified Free plan throws.
+ */
+export const assertAiGatewayProvisionable = async (params) => {
+    let subscriptionType;
+    let orgId;
+    try {
+        const { data } = await params.apiClient.getProject(params.projectId);
+        subscriptionType = data.project.owner?.subscription_type;
+        orgId = data.project.org_id ?? undefined;
+    }
+    catch {
+        return; // Can't determine the plan — don't block.
+    }
+    if (isFreePlan(subscriptionType)) {
+        throw new Error(freePlanBlockMessage(aiGatewayUpgradeUrl(orgId)));
+    }
+};
+/**
+ * Resolve the account's plan (and, when gateway credentials are on hand, its live model
+ * catalog) and print the AI Gateway courtesy notice — used by the `neon.ts` lifecycle and
+ * `env pull` whenever a branch has the gateway enabled.
+ *
+ * Pass `gateway` (base URL + token) to enable the reduced-model-set check; omit it (e.g. a
+ * dry-run `plan`) to get only the Free-plan notice. This is best-effort: any failure while
+ * fetching the plan or catalog is swallowed so it can never break the underlying command.
+ */
+export const warnAiGateway = async (params) => {
+    try {
+        const { data } = await params.apiClient.getProject(params.projectId);
+        const subscriptionType = data.project.owner?.subscription_type;
+        const orgId = data.project.org_id ?? undefined;
+        const modelIds = params.gateway
+            ? ((await fetchGatewayModelIds(params.gateway.baseUrl, params.gateway.token)) ?? undefined)
+            : undefined;
+        const notice = buildAiGatewayNotice({
+            subscriptionType,
+            modelIds,
+            upgradeUrl: aiGatewayUpgradeUrl(orgId),
+            moreModelsUrl: aiGatewayModelsUrl(params.projectId, params.branchId),
+        });
+        if (notice)
+            log.warning(notice.message);
+    }
+    catch {
+        // A courtesy notice must never break the command that triggered it.
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neonctl",
-  "version": "2.32.0",
+  "version": "2.33.1",
   "description": "CLI tool for Neon Serverless Postgres",
   "keywords": [
     "neon",
@@ -42,7 +42,7 @@
     "cliui": "8.0.1",
     "diff": "5.2.0",
     "fflate": "^0.8.3",
-    "neon-init": "0.20.0",
+    "neon-init": "0.20.2",
     "open": "^10.2.0",
     "openid-client": "6.8.1",
     "pg-protocol": "^1.14.0",
@@ -51,10 +51,10 @@
     "which": "3.0.1",
     "yaml": "^2.9.0",
     "yargs": "17.7.2",
-    "@neon/sdk": "1.1.0",
-    "@neon/config": "0.9.2",
-    "@neon/config-runtime": "0.9.2",
-    "@neon/env": "0.11.1"
+    "@neon/sdk": "1.1.1",
+    "@neon/config-runtime": "0.9.4",
+    "@neon/env": "0.11.3",
+    "@neon/config": "0.9.4"
   },
   "optionalDependencies": {
     "esbuild": "0.28.1"