neonctl 2.27.0 → 2.28.0

package/dist/current_branch_fast_path.js

@@ -0,0 +1,55 @@
+import { contextBranch, currentContextFile, readContextFile } from './context.js';
+import { log } from './log.js';
+/**
+ * Offline fast path for `(config) status --current-branch` (used by shell prompts).
+ *
+ * Reading the pinned branch out of the local `.neon` file does not need the CLI's
+ * full command tree, `@neondatabase/api-client`, or yargs — importing those is ~200ms,
+ * which dwarfs the actual work. So the entry point ({@link file://./cli.ts}) calls this
+ * BEFORE importing `index.js`, and only falls through to the full CLI when this returns
+ * `false`. On the fast path the process loads only this module + `context.js`/`log.js`
+ * (~25ms total incl. Node startup) instead of ~230ms.
+ *
+ * It mirrors the `--current-branch` short-circuit in `status()` (commands/config.ts):
+ * print the pinned branch to stdout and exit 0, or print nothing + a `neonctl checkout`
+ * hint on stderr and exit non-zero when no branch is pinned.
+ *
+ * Deliberately conservative: only the EXACT bare invocation is handled —
+ * `status --current-branch` or `config status --current-branch` with no other args.
+ * Anything else (extra flags like `--context-file`/`--output`, more args, etc.) returns
+ * `false` and flows through the normal yargs pipeline, so behavior can never diverge —
+ * the worst case is "not faster", never "wrong".
+ *
+ * @returns `true` if it handled the invocation (caller should NOT load the full CLI).
+ */
+export const tryCurrentBranchFastPath = (argv, 
+// `cwd` is overridable so tests can exercise the `.neon` walk-up without mutating
+// `process.cwd()` (which isn't allowed in vitest workers), mirroring currentContextFile.
+cwd = process.cwd()) => {
+    // argv is [execPath, scriptPath, ...userArgs].
+    if (!isExactCurrentBranchInvocation(argv.slice(2))) {
+        return false;
+    }
+    const branch = contextBranch(readContextFile(currentContextFile(cwd)));
+    if (branch) {
+        process.stdout.write(`${branch}\n`);
+    }
+    else {
+        log.info('No branch pinned. Run `neonctl checkout <branch>` to pin a branch and pull its env vars.');
+        process.exitCode = 1;
+    }
+    return true;
+};
+/**
+ * True only for `status --current-branch` or `config status --current-branch` with no
+ * other arguments. Any extra token (another flag, `--context-file`, `=`-style flags,
+ * positional args) makes this false so the full CLI handles it.
+ */
+const isExactCurrentBranchInvocation = (args) => {
+    const rest = args[0] === 'status'
+        ? args.slice(1)
+        : args[0] === 'config' && args[1] === 'status'
+            ? args.slice(2)
+            : null;
+    return rest !== null && rest.length === 1 && rest[0] === '--current-branch';
+};

package/dist/errors.js

@@ -0,0 +1,80 @@
+const ERROR_MATCHERS = [
+    [/^Unknown command: (.*)$/, 'UNKNOWN_COMMAND'],
+    [/^Missing required argument: (.*)$/, 'MISSING_ARGUMENT'],
+    [/^Failed to open web browser. (.*)$/, 'AUTH_BROWSER_FAILED'],
+];
+export const matchErrorCode = (message) => {
+    if (!message) {
+        return 'UNKNOWN_ERROR';
+    }
+    for (const [matcher, code] of ERROR_MATCHERS) {
+        const match = message.match(matcher);
+        if (match) {
+            return code;
+        }
+    }
+    return 'UNKNOWN_ERROR';
+};
+/**
+ * The single, human-readable line shown when the CLI couldn't reach the Neon API because
+ * of a connection-level failure (DNS, refused/reset connection, offline). It replaces the
+ * cryptic `fetch failed` / empty axios message a network blip otherwise surfaces (see
+ * {@link isNetworkError}), pointing at the two things the user can actually check.
+ */
+export const NETWORK_ERROR_MESSAGE = 'Could not reach the Neon API. Please check your internet connection and try again. ' +
+    'If your connection is fine and this keeps happening, check https://neonstatus.com for ongoing incidents.';
+/**
+ * Node-level socket/DNS error codes that mean the request never reached the server — a
+ * genuine connectivity problem rather than an API response we should surface. Deliberately
+ * excludes `ECONNABORTED` (axios' timeout), which the CLI already reports as a timeout.
+ */
+const NETWORK_ERROR_CODES = new Set([
+    'ECONNREFUSED',
+    'ECONNRESET',
+    'ETIMEDOUT',
+    'ENOTFOUND',
+    'EAI_AGAIN',
+    'EPIPE',
+    'EHOSTUNREACH',
+    'ENETUNREACH',
+    'EHOSTDOWN',
+    'ENETDOWN',
+]);
+/**
+ * Message fragments that mark a connection-level failure across our two transports: the
+ * `@neon/sdk` / global `fetch` path (used by `env pull` / `config` / `deploy`, and `link`'s
+ * bundled env pull) throws a bare `TypeError: fetch failed` / "Failed to fetch", while the
+ * axios `api-client` path throws an `AxiosError` whose message is "Network Error".
+ */
+const NETWORK_ERROR_MESSAGE_PATTERN = /fetch failed|failed to fetch|network error/i;
+const readErrorCode = (value) => {
+    if (value === null || typeof value !== 'object')
+        return undefined;
+    const code = value.code;
+    return typeof code === 'string' ? code : undefined;
+};
+/**
+ * Whether `err` is a connection-level failure (the network blip the user sees as a cryptic
+ * `fetch failed`, or no message at all on the axios path) rather than an actual API response.
+ *
+ * A Node `fetch` failure is a bare `TypeError: fetch failed` whose underlying `cause` carries
+ * the real socket `code` (e.g. `ECONNREFUSED`, `ENOTFOUND`, `EAI_AGAIN`), so we walk the
+ * `cause` chain checking both the code and the message. This is what lets the CLI swap the
+ * confusing default for {@link NETWORK_ERROR_MESSAGE}. It matches only failures where no
+ * response was ever received, so it never masks a real 4xx/5xx the user needs to see.
+ */
+export const isNetworkError = (err) => {
+    let current = err;
+    for (let depth = 0; depth < 6 && current !== null && current !== undefined; depth++) {
+        const code = readErrorCode(current);
+        if (code !== undefined && NETWORK_ERROR_CODES.has(code)) {
+            return true;
+        }
+        if (current instanceof Error &&
+            NETWORK_ERROR_MESSAGE_PATTERN.test(current.message)) {
+            return true;
+        }
+        current = current.cause;
+    }
+    return false;
+};

package/{functions_api.js → dist/functions_api.js}

@@ -1,4 +1,4 @@
-import { ContentType } from '@neondatabase/api-client';
+import { ContentType } from './api.js';
 const functionsPath = (projectId, branchId) => `/projects/${encodeURIComponent(projectId)}/branches/${encodeURIComponent(branchId)}/functions`;
 export const listFunctions = async (apiClient, projectId, branchId, { cursor, limit } = {}) => {
     const { data } = await apiClient.request({

package/{index.js → dist/index.js}

@@ -1,18 +1,7 @@
 import { basename } from 'node:path';
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
-import axiosDebug from 'axios-debug-log';
-axiosDebug({
-    request(debug, config) {
-        debug(`${config.method?.toUpperCase()} ${config.url}`);
-    },
-    response(debug, response) {
-        debug(`${response.status} ${response.statusText}`);
-    },
-    error(debug, error) {
-        debug(error);
-    },
-});
+import { isNeonApiError, messageFromBody } from './api.js';
 import { ensureAuth, deleteCredentials } from './commands/auth.js';
 import { defaultDir, ensureConfigDir } from './config.js';
 import { log } from './log.js';
@@ -21,8 +10,7 @@ import { fillInArgs } from './utils/middlewares.js';
 import pkg from './pkg.js';
 import commands from './commands/index.js';
 import { analyticsMiddleware, initAnalyticsClientMiddleware, closeAnalytics, getAnalyticsEventProperties, sendError, trackEvent, } from './analytics.js';
-import { isAxiosError } from 'axios';
-import { matchErrorCode } from './errors.js';
+import { isNetworkError, matchErrorCode, NETWORK_ERROR_MESSAGE, } from './errors.js';
 import { showHelp } from './help.js';
 import { currentContextFile, enrichFromContext } from './context.js';
 const NO_SUBCOMMANDS_VERBS = [
@@ -41,7 +29,8 @@ const NO_SUBCOMMANDS_VERBS = [
     'dev',
     'deploy',
     'bootstrap',
-    // aliases
+    // alias of `config status`
+    'status',
 ];
 let builder = yargs(hideBin(process.argv));
 builder = builder
@@ -161,13 +150,24 @@ async function handleError(msg, err) {
     if (err instanceof Error && err.stack) {
         log.debug('Stack: %s', err.stack);
     }
-    if (isAxiosError(err)) {
+    // A connection-level failure (no response ever reached us) reads as a cryptic
+    // `fetch failed` from the @neon/sdk / global `fetch` path. Detect it first and
+    // swap in one clear "check your connection" hint. We deliberately do not retry
+    // here: re-running the whole command could re-trigger a non-idempotent step
+    // (e.g. project create), so retries belong at the request layer.
+    if (isNetworkError(err)) {
+        log.error(NETWORK_ERROR_MESSAGE);
+        const error = err instanceof Error ? err : new Error(NETWORK_ERROR_MESSAGE);
+        sendError(error, 'NETWORK_ERROR');
+        return false;
+    }
+    if (isNeonApiError(err)) {
         if (err.code === 'ECONNABORTED') {
             log.error('Request timed out');
             sendError(err, 'REQUEST_TIMEOUT');
             return false;
         }
-        else if (err.response?.status === 401) {
+        else if (err.status === 401) {
             sendError(err, 'AUTH_FAILED');
             log.info('Authentication failed, deleting credentials...');
             try {
@@ -180,10 +180,11 @@ async function handleError(msg, err) {
             }
         }
         else {
-            if (err.response?.data?.message) {
-                log.error(err.response?.data?.message);
+            const serverMessage = messageFromBody(err.data);
+            if (serverMessage) {
+                log.error(serverMessage);
             }
-            log.debug('status: %d %s | path: %s', err.response?.status, err.response?.statusText, err.request?.path);
+            log.debug('status: %d %s | path: %s', err.status, err.statusText, err.requestPath);
             sendError(err, 'API_ERROR');
             return false;
         }

package/{parameters.gen.js → dist/parameters.gen.js}

@@ -108,17 +108,17 @@ export const projectCreateRequest = {
     },
     'project.provisioner': {
         type: "string",
-        description: "The Neon compute provisioner.\nSpecify the `k8s-neonvm` provisioner to create a compute endpoint that supports Autoscaling.\n\nProvisioner can be one of the following values:\n* k8s-pod\n* k8s-neonvm\n\nClients must expect, that any string value that is not documented in the description above should be treated as a error. UNKNOWN value if safe to treat as an error too.\n",
+        description: "The Neon compute provisioner.\nSpecify the `k8s-neonvm` provisioner to create a compute endpoint that supports Autoscaling.\n\nProvisioner can be one of the following values:\n* k8s-pod\n* k8s-neonvm\n* serverless-platform\n\nClients must expect, that any string value that is not documented in the description above should be treated as a error. UNKNOWN value if safe to treat as an error too.\n",
         demandOption: false,
     },
     'project.region_id': {
         type: "string",
-        description: "The region identifier. Refer to our [Regions](https://neon.tech/docs/introduction/regions) documentation for supported regions. Values are specified in this format: `aws-us-east-1`\n",
+        description: "The region identifier. Refer to our [Regions](https://neon.com/docs/introduction/regions) documentation for supported regions. Values are specified in this format: `aws-us-east-1`\n",
         demandOption: false,
     },
     'project.default_endpoint_settings.suspend_timeout_seconds': {
         type: "number",
-        description: "Duration of inactivity in seconds after which the compute endpoint is\nautomatically suspended. The value `0` means use the default value.\nThe value `-1` means never suspend. The default value is `300` seconds (5 minutes).\nThe minimum value is `60` seconds (1 minute).\nThe maximum value is `604800` seconds (1 week). For more information, see\n[Scale to zero configuration](https://neon.tech/docs/manage/endpoints#scale-to-zero-configuration).\n",
+        description: "Duration of inactivity in seconds after which the compute endpoint is\nautomatically suspended. The value `0` means use the default value.\nThe value `-1` means never suspend. The default value is `300` seconds (5 minutes).\nThe minimum value is `60` seconds (1 minute).\nThe maximum value is `604800` seconds (1 week). For more information, see\n[Scale to zero configuration](https://neon.com/docs/manage/endpoints#scale-to-zero-configuration).\n",
         demandOption: false,
     },
     'project.pg_version': {
@@ -236,7 +236,7 @@ export const projectUpdateRequest = {
     },
     'project.default_endpoint_settings.suspend_timeout_seconds': {
         type: "number",
-        description: "Duration of inactivity in seconds after which the compute endpoint is\nautomatically suspended. The value `0` means use the default value.\nThe value `-1` means never suspend. The default value is `300` seconds (5 minutes).\nThe minimum value is `60` seconds (1 minute).\nThe maximum value is `604800` seconds (1 week). For more information, see\n[Scale to zero configuration](https://neon.tech/docs/manage/endpoints#scale-to-zero-configuration).\n",
+        description: "Duration of inactivity in seconds after which the compute endpoint is\nautomatically suspended. The value `0` means use the default value.\nThe value `-1` means never suspend. The default value is `300` seconds (5 minutes).\nThe minimum value is `60` seconds (1 minute).\nThe maximum value is `604800` seconds (1 week). For more information, see\n[Scale to zero configuration](https://neon.com/docs/manage/endpoints#scale-to-zero-configuration).\n",
         demandOption: false,
     },
     'project.history_retention_seconds': {
@@ -311,12 +311,12 @@ export const branchCreateRequestEndpointOptions = {
     },
     'provisioner': {
         type: "string",
-        description: "The Neon compute provisioner.\nSpecify the `k8s-neonvm` provisioner to create a compute endpoint that supports Autoscaling.\n\nProvisioner can be one of the following values:\n* k8s-pod\n* k8s-neonvm\n\nClients must expect, that any string value that is not documented in the description above should be treated as a error. UNKNOWN value if safe to treat as an error too.\n",
+        description: "The Neon compute provisioner.\nSpecify the `k8s-neonvm` provisioner to create a compute endpoint that supports Autoscaling.\n\nProvisioner can be one of the following values:\n* k8s-pod\n* k8s-neonvm\n* serverless-platform\n\nClients must expect, that any string value that is not documented in the description above should be treated as a error. UNKNOWN value if safe to treat as an error too.\n",
         demandOption: false,
     },
     'suspend_timeout_seconds': {
         type: "number",
-        description: "Duration of inactivity in seconds after which the compute endpoint is\nautomatically suspended. The value `0` means use the default value.\nThe value `-1` means never suspend. The default value is `300` seconds (5 minutes).\nThe minimum value is `60` seconds (1 minute).\nThe maximum value is `604800` seconds (1 week). For more information, see\n[Scale to zero configuration](https://neon.tech/docs/manage/endpoints#scale-to-zero-configuration).\n",
+        description: "Duration of inactivity in seconds after which the compute endpoint is\nautomatically suspended. The value `0` means use the default value.\nThe value `-1` means never suspend. The default value is `300` seconds (5 minutes).\nThe minimum value is `60` seconds (1 minute).\nThe maximum value is `604800` seconds (1 week). For more information, see\n[Scale to zero configuration](https://neon.com/docs/manage/endpoints#scale-to-zero-configuration).\n",
         demandOption: false,
     },
 };
@@ -366,17 +366,17 @@ export const endpointCreateRequest = {
     },
     'endpoint.provisioner': {
         type: "string",
-        description: "The Neon compute provisioner.\nSpecify the `k8s-neonvm` provisioner to create a compute endpoint that supports Autoscaling.\n\nProvisioner can be one of the following values:\n* k8s-pod\n* k8s-neonvm\n\nClients must expect, that any string value that is not documented in the description above should be treated as a error. UNKNOWN value if safe to treat as an error too.\n",
+        description: "The Neon compute provisioner.\nSpecify the `k8s-neonvm` provisioner to create a compute endpoint that supports Autoscaling.\n\nProvisioner can be one of the following values:\n* k8s-pod\n* k8s-neonvm\n* serverless-platform\n\nClients must expect, that any string value that is not documented in the description above should be treated as a error. UNKNOWN value if safe to treat as an error too.\n",
         demandOption: false,
     },
     'endpoint.pooler_enabled': {
         type: "boolean",
-        description: "Whether to enable connection pooling for the compute endpoint\n",
+        description: "DEPRECATED. Whether to enable connection pooling for the compute endpoint.\nThe recommended way to enable connection pooling is to append `-pooler` to the endpoint ID in the connection string.\nSee [How to use connection pooling](https://neon.com/docs/connect/connection-pooling#how-to-use-connection-pooling)\n",
         demandOption: false,
     },
     'endpoint.pooler_mode': {
         type: "string",
-        description: "The connection pooler mode. Neon supports PgBouncer in `transaction` mode only.\n",
+        description: "DEPRECATED. The connection pooler mode. This field is deprecated and will be removed after 2026-06-20.\n",
         demandOption: false,
         choices: ["transaction"],
     },
@@ -392,7 +392,7 @@ export const endpointCreateRequest = {
     },
     'endpoint.suspend_timeout_seconds': {
         type: "number",
-        description: "Duration of inactivity in seconds after which the compute endpoint is\nautomatically suspended. The value `0` means use the default value.\nThe value `-1` means never suspend. The default value is `300` seconds (5 minutes).\nThe minimum value is `60` seconds (1 minute).\nThe maximum value is `604800` seconds (1 week). For more information, see\n[Scale to zero configuration](https://neon.tech/docs/manage/endpoints#scale-to-zero-configuration).\n",
+        description: "Duration of inactivity in seconds after which the compute endpoint is\nautomatically suspended. The value `0` means use the default value.\nThe value `-1` means never suspend. The default value is `300` seconds (5 minutes).\nThe minimum value is `60` seconds (1 minute).\nThe maximum value is `604800` seconds (1 week). For more information, see\n[Scale to zero configuration](https://neon.com/docs/manage/endpoints#scale-to-zero-configuration).\n",
         demandOption: false,
     },
     'endpoint.name': {
@@ -409,7 +409,7 @@ export const endpointUpdateRequest = {
     },
     'endpoint.provisioner': {
         type: "string",
-        description: "The Neon compute provisioner.\nSpecify the `k8s-neonvm` provisioner to create a compute endpoint that supports Autoscaling.\n\nProvisioner can be one of the following values:\n* k8s-pod\n* k8s-neonvm\n\nClients must expect, that any string value that is not documented in the description above should be treated as a error. UNKNOWN value if safe to treat as an error too.\n",
+        description: "The Neon compute provisioner.\nSpecify the `k8s-neonvm` provisioner to create a compute endpoint that supports Autoscaling.\n\nProvisioner can be one of the following values:\n* k8s-pod\n* k8s-neonvm\n* serverless-platform\n\nClients must expect, that any string value that is not documented in the description above should be treated as a error. UNKNOWN value if safe to treat as an error too.\n",
         demandOption: false,
     },
     'endpoint.settings.preload_libraries.use_defaults': {
@@ -424,12 +424,12 @@ export const endpointUpdateRequest = {
     },
     'endpoint.pooler_enabled': {
         type: "boolean",
-        description: "Whether to enable connection pooling for the compute endpoint\n",
+        description: "DEPRECATED. Whether to enable connection pooling for the compute endpoint.\nThe recommended way to enable connection pooling is to append `-pooler` to the endpoint ID in the connection string.\nSee [How to use connection pooling](https://neon.com/docs/connect/connection-pooling#how-to-use-connection-pooling)\n",
         demandOption: false,
     },
     'endpoint.pooler_mode': {
         type: "string",
-        description: "The connection pooler mode. Neon supports PgBouncer in `transaction` mode only.\n",
+        description: "DEPRECATED. The connection pooler mode. This field is deprecated and will be removed after 2026-06-20.\n",
         demandOption: false,
         choices: ["transaction"],
     },
@@ -445,7 +445,7 @@ export const endpointUpdateRequest = {
     },
     'endpoint.suspend_timeout_seconds': {
         type: "number",
-        description: "Duration of inactivity in seconds after which the compute endpoint is\nautomatically suspended. The value `0` means use the default value.\nThe value `-1` means never suspend. The default value is `300` seconds (5 minutes).\nThe minimum value is `60` seconds (1 minute).\nThe maximum value is `604800` seconds (1 week). For more information, see\n[Scale to zero configuration](https://neon.tech/docs/manage/endpoints#scale-to-zero-configuration).\n",
+        description: "Duration of inactivity in seconds after which the compute endpoint is\nautomatically suspended. The value `0` means use the default value.\nThe value `-1` means never suspend. The default value is `300` seconds (5 minutes).\nThe minimum value is `60` seconds (1 minute).\nThe maximum value is `604800` seconds (1 week). For more information, see\n[Scale to zero configuration](https://neon.com/docs/manage/endpoints#scale-to-zero-configuration).\n",
         demandOption: false,
     },
     'endpoint.name': {

package/{storage_api.js → dist/storage_api.js}

@@ -1,14 +1,13 @@
 // Typed client helpers for the branch object-storage (bucket/object) API.
 //
 // These endpoints are part of the Neon object-storage surface (the "Buckets"
-// tag in the public API). They are not yet exposed as typed methods on the
-// published `@neondatabase/api-client` package, so the request/response types
-// and the thin call helpers live here. They are implemented on top of the
-// api-client's public `request()` method, which means they reuse the exact
-// same authentication, base URL, headers and retry behaviour as every other
-// neonctl command. When the generated client gains these methods, the call
-// sites in `src/commands/bucket.ts` can switch over with no behavioural
-// change.
+// tag in the public API). They are not yet exposed as typed methods on
+// `@neon/sdk`, so the request/response types and the thin call helpers live
+// here. They are implemented on top of the API client's low-level `request()`
+// method, which reuses the exact same authentication, base URL, headers and
+// retry behaviour as every other neonctl command. When the SDK gains these
+// methods, the call sites in `src/commands/bucket.ts` can switch over with no
+// behavioural change.
 const bucketsPath = (projectId, branchId) => `/projects/${encodeURIComponent(projectId)}/branches/${encodeURIComponent(branchId)}/buckets`;
 const bucketPath = (projectId, branchId, bucketName) => `${bucketsPath(projectId, branchId)}/${encodeURIComponent(bucketName)}`;
 /**

package/{test_utils → dist/test_utils}/fixtures.js

@@ -1,3 +1,4 @@
+import { createServer } from 'node:http';
 import { fork } from 'node:child_process';
 import { join } from 'node:path';
 import { expect, test as originalTest } from 'vitest';
@@ -5,41 +6,70 @@ import strip from 'strip-ansi';
 import emocks from 'emocks';
 import express from 'express';
 import { log } from '../log';
+/**
+ * Reserve a localhost port and close its listener, returning a URL that is guaranteed to
+ * refuse connections right now. Lets a test drive the CLI into a real `ECONNREFUSED`
+ * (the same shape a network blip produces) deterministically and fast.
+ */
+const reserveClosedPort = () => new Promise((resolve, reject) => {
+    const probe = createServer();
+    probe.on('error', reject);
+    probe.listen(0, '127.0.0.1', () => {
+        const { port } = probe.address();
+        probe.close((err) => {
+            if (err) {
+                reject(err);
+            }
+            else {
+                resolve(`http://127.0.0.1:${port}`);
+            }
+        });
+    });
+});
 export const test = originalTest.extend({
     // eslint-disable-next-line no-empty-pattern
     runMockServer: async ({}, use) => {
-        let server;
+        let startedServer;
         await use(async (mockDir) => {
             const app = express();
             app.use(express.json());
             app.use('/', emocks(join(process.cwd(), 'mocks', mockDir), {
                 '404': (_req, res) => res.status(404).send({ message: 'Not Found' }),
             }));
-            await new Promise((resolve) => {
-                server = app.listen(0, () => {
-                    resolve();
-                    log.debug('Mock server listening at %d', server.address().port);
+            const server = await new Promise((resolve) => {
+                const s = app.listen(0, () => {
+                    log.debug('Mock server listening at %d', s.address().port);
+                    resolve(s);
                 });
             });
+            startedServer = server;
             return server;
         });
-        await new Promise((resolve, reject) => server.close((err) => {
-            if (err) {
-                reject(err instanceof Error ? err : new Error(String(err)));
-            }
-            else {
-                resolve();
-            }
-        }));
+        // `unreachableHost` tests never start the server, so only close it when it ran.
+        const server = startedServer;
+        if (server) {
+            await new Promise((resolve, reject) => {
+                server.close((err) => {
+                    if (err) {
+                        reject(err instanceof Error ? err : new Error(String(err)));
+                    }
+                    else {
+                        resolve();
+                    }
+                });
+            });
+        }
     },
     testCliCommand: async ({ runMockServer }, use) => {
         await use(async (args, options = {}) => {
-            const server = await runMockServer(options.mockDir || 'main');
+            const apiHost = options.unreachableHost
+                ? await reserveClosedPort()
+                : `http://localhost:${(await runMockServer(options.mockDir || 'main')).address().port}`;
             let output = '';
             let error = '';
             const cp = fork(join(process.cwd(), './dist/index.js'), [
                 '--api-host',
-                `http://localhost:${server.address().port}`,
+                apiHost,
                 '--output',
                 options.output ?? (options.outputTable ? 'table' : 'yaml'),
                 '--api-key',

package/dist/utils/api_enums.js

@@ -0,0 +1,33 @@
+// Runtime enum-like constants for Neon API string unions.
+//
+// `@neondatabase/api-client` generated TypeScript `enum`s (real runtime objects)
+// for fields like the compute endpoint type. `@neon/sdk` instead models these as
+// plain string-literal union *types*, which have no runtime value — so code that
+// read `EndpointType.ReadWrite` or `Object.values(EndpointType)` no longer works.
+//
+// These `as const` objects restore that runtime surface, and each is paired with
+// a same-named type whose union is identical to the corresponding `@neon/sdk`
+// type, so values stay assignable in both directions.
+export const EndpointType = {
+    ReadOnly: 'read_only',
+    ReadWrite: 'read_write',
+};
+export const NeonAuthOauthProviderId = {
+    Google: 'google',
+    Github: 'github',
+    Microsoft: 'microsoft',
+    Vercel: 'vercel',
+};
+export const NeonAuthOauthProviderType = {
+    Standard: 'standard',
+    Shared: 'shared',
+};
+export const NeonAuthSupportedAuthProvider = {
+    Mock: 'mock',
+    Stack: 'stack',
+    BetterAuth: 'better_auth',
+};
+export const NeonAuthEmailVerificationMethod = {
+    Link: 'link',
+    Otp: 'otp',
+};

package/{utils → dist/utils}/branch_picker.js

@@ -1,4 +1,4 @@
-import { EndpointType } from '@neondatabase/api-client';
+import { EndpointType } from './api_enums.js';
 import prompts from 'prompts';
 import { retryOnLock } from '../api.js';
 import { log } from '../log.js';

package/{utils → dist/utils}/enrichers.js

@@ -1,5 +1,6 @@
+import { isCurrentBranchProbe } from '../context.js';
 import { looksLikeBranchId } from './formats.js';
-import { isAxiosError } from 'axios';
+import { isNeonApiError, messageFromBody } from '../api.js';
 export const branchIdResolve = async ({ branch, apiClient, projectId, }) => {
     branch = branch.toString();
     if (looksLikeBranchId(branch)) {
@@ -97,6 +98,12 @@ export const resolveSingleDatabase = async (props) => {
     throw new Error(`Multiple databases found for the branch, please provide one with the --database option: ${databases.map((d) => d.name).join(', ')}`);
 };
 export const fillSingleProject = async (props) => {
+    // The offline `--current-branch` probe needs no project at all and runs with no
+    // API client (auth was skipped), so resolving a single project here would both
+    // hit the network and dereference a null client. Skip it entirely.
+    if (isCurrentBranchProbe(props)) {
+        return props;
+    }
     if (props.projectId) {
         return { ...props, projectId: props.projectId };
     }
@@ -126,9 +133,9 @@ export const fillSingleProject = async (props) => {
     }
     catch (error) {
         // If the API error is about missing org_id, provide a user-friendly message
-        if (isAxiosError(error) &&
-            error.response?.status === 400 &&
-            error.response?.data?.message?.includes('org_id is required')) {
+        if (isNeonApiError(error) &&
+            error.status === 400 &&
+            messageFromBody(error.data)?.includes('org_id is required')) {
             throw new Error('Multiple projects found, please provide one with the --project-id option');
         }
         throw error;