neonctl 2.26.2 → 2.26.3

package/README.md

@@ -455,7 +455,7 @@ The target directory must be empty unless you pass `--force` (a lone `.git` is i
 | [me](https://neon.com/docs/reference/cli-me)                               |                                                                                                              | Show current user                  |
 | [branches](https://neon.com/docs/reference/cli-branches)                   | `list`, `create`, `rename`, `add-compute`, `set-default`, `set-expiration`, `delete`, `get`                  | Manage branches                    |
 | [databases](https://neon.com/docs/reference/cli-databases)                 | `list`, `create`, `delete`                                                                                   | Manage databases                   |
-| functions                                                                  | `deploy`, `list`, `get`, `delete`                                                                            | Manage Neon Functions              |
+| function                                                                   | `deploy`, `list`, `get`, `delete`                                                                            | Manage Neon Functions              |
 | [roles](https://neon.com/docs/reference/cli-roles)                         | `list`, `create`, `delete`                                                                                   | Manage roles                       |
 | [operations](https://neon.com/docs/reference/cli-operations)               | `list`                                                                                                       | Manage operations                  |
 | [connection-string](https://neon.com/docs/reference/cli-connection-string) |                                                                                                              | Get connection string              |

package/commands/bucket.js

@@ -95,7 +95,7 @@ export const builder = (argv) => argv
     .command({
     command: 'list <target>',
     aliases: ['ls'],
-    describe: 'List objects in a bucket',
+    describe: 'List objects in a bucket. By default folders are collapsed (like "aws s3 ls"); pass --recursive for a flat listing of every key',
     builder: (yargs) => yargs
         .usage('$0 bucket object list <bucket>[/<prefix>] [options]')
         .positional('target', {
@@ -105,8 +105,13 @@ export const builder = (argv) => argv
     })
         .options({
         ...scopeOptions,
+        recursive: {
+            describe: 'List every key flat, descending into nested folders (no delimiter). Mutually exclusive with --delimiter. Mirrors "aws s3 ls --recursive"',
+            type: 'boolean',
+            default: false,
+        },
         delimiter: {
-            describe: 'Collapse keys sharing a common prefix (e.g. "/") into folders',
+            describe: 'Collapse keys sharing this prefix separator into folders. Defaults to "/" (folder view); ignored when --recursive is set',
             type: 'string',
         },
         cursor: {
@@ -223,7 +228,26 @@ const deleteBucket = async (props) => {
     }
     log.info(`Bucket "${props.name}" deleted from branch ${branchId}`);
 };
+// Resolve the delimiter to send to the backend, mirroring `aws s3 ls`:
+//   - default (neither flag): "/" so the listing is folder-collapsed;
+//   - --recursive: no delimiter, so every nested key is returned flat;
+//   - explicit --delimiter <x>: that value (an empty string lists flat too).
+// `--recursive` together with an explicit `--delimiter` is nonsensical and is
+// rejected client-side before any HTTP request is made.
+export const resolveListDelimiter = (props) => {
+    if (props.recursive && props.delimiter !== undefined) {
+        throw new Error('--recursive and --delimiter cannot be used together. Use --recursive for a flat listing, or --delimiter to collapse on a separator.');
+    }
+    if (props.recursive) {
+        return undefined;
+    }
+    if (props.delimiter !== undefined) {
+        return props.delimiter;
+    }
+    return '/';
+};
 const listObjects = async (props) => {
+    const delimiter = resolveListDelimiter(props);
     const branchId = await branchIdFromProps(props);
     const { bucket, rest } = splitBucketTarget(props.target);
     const { data } = await listProjectBranchBucketObjects(props.apiClient, {
@@ -231,7 +255,7 @@ const listObjects = async (props) => {
         branchId,
         bucketName: bucket,
         prefix: rest === '' ? undefined : rest,
-        delimiter: props.delimiter,
+        delimiter,
         cursor: props.cursor,
         limit: props.limit,
     });

package/commands/config.js

@@ -1,7 +1,9 @@
+import chalk from 'chalk';
 import { resolveConfig } from '@neondatabase/config';
 import { apply, createBranch as createBranchFromPolicy, inspect, loadConfigFromFile, plan, } from '@neondatabase/config-runtime';
 import { toNeonConfigView } from '../config_format.js';
 import { log } from '../log.js';
+import { isCi } from '../env.js';
 import { loadEnvFileIntoProcess } from '../env_file.js';
 import { fillSingleProject, resolveBranchRef } from '../utils/enrichers.js';
 import { announceTargetBranch } from '../utils/branch_notice.js';
@@ -17,8 +19,12 @@ import { autoPullEnvAfterPin } from './env.js';
  */
 const neonctlBundler = async (fn) => zipBundle(await bundleEntry(fn.source));
 const INSPECT_FIELDS = ['project', 'branch', 'config'];
-const APPLIED_FIELDS = ['action', 'kind', 'identifier', 'details'];
-const FUNCTION_FIELDS = ['slug', 'invocation_url'];
+// Deliberately minimal: action/kind/identifier are short and fixed-ish, so the table can
+// never overflow. Per-change `details` (a function's long invocationUrl in particular) are
+// intentionally NOT a column — they used to be JSON-stringified into a cell and blew the
+// table past 190 cols. Function URLs are printed below as a plain list (see reportPushResult),
+// and the full details are still available via `--output json`.
+const APPLIED_FIELDS = ['action', 'kind', 'identifier'];
 const CONFLICT_FIELDS = [
     'identifier',
     'field',
@@ -252,7 +258,6 @@ const reportPushResult = (props, result, mode, services) => {
         action: change.action,
         kind: change.kind,
         identifier: change.identifier,
-        details: change.details ? JSON.stringify(change.details) : '',
     }));
     const conflicts = result.conflicts.map((conflict) => ({
         identifier: conflict.identifier,
@@ -261,9 +266,9 @@ const reportPushResult = (props, result, mode, services) => {
         desired: stringify(conflict.desired),
         reason: conflict.reason,
     }));
-    // Deployed functions carry their invocation URL in the change details — pull them into a
-    // dedicated table so users can see where to call each function without digging through the
-    // raw details blob. Keyed by slug so a function never shows twice.
+    // Deployed functions carry their invocation URL in the change details — collect them so
+    // we can list where to call each function without digging through the raw details blob.
+    // Keyed by slug so a function never shows twice.
     const functionUrlBySlug = new Map();
     for (const change of result.applied) {
         if (change.action === 'noop')
@@ -274,10 +279,6 @@ const reportPushResult = (props, result, mode, services) => {
             functionUrlBySlug.set(slug, invocationUrl);
         }
     }
-    const functions = [...functionUrlBySlug].map(([slug, invocation_url]) => ({
-        slug,
-        invocation_url,
-    }));
     const out = writer(props);
     const noChanges = changes.length === 0 && conflicts.length === 0;
     if (changes.length > 0) {
@@ -286,17 +287,21 @@ const reportPushResult = (props, result, mode, services) => {
             title: mode === 'plan' ? 'Planned changes' : 'Applied changes',
         });
     }
-    if (functions.length > 0) {
-        out.write(functions, {
-            fields: FUNCTION_FIELDS,
-            title: mode === 'plan' ? 'Function URLs (after apply)' : 'Function URLs',
-        });
-    }
     if (conflicts.length > 0) {
         out.write(conflicts, { fields: CONFLICT_FIELDS, title: 'Conflicts' });
     }
-    // Flush any tables, then append the summary so it reads directly below them.
+    // Flush any tables, then append the lists/summary so they read directly below them.
     out.end();
+    // Function URLs are a plain list rather than a table: an invocation URL can be 70+ chars,
+    // which makes any bordered table overflow and wrap awkwardly in a normal terminal. A list
+    // lets each URL reflow on its own line, and stays copy-pasteable.
+    if (functionUrlBySlug.size > 0) {
+        const heading = mode === 'plan' ? 'Function URLs (after apply)' : 'Function URLs';
+        out.text(`\n${isCi() ? heading : chalk.bold(heading)}\n`);
+        for (const [slug, invocationUrl] of functionUrlBySlug) {
+            out.text(`  • ${slug}: ${invocationUrl}\n`);
+        }
+    }
     if (noChanges) {
         log.info(`No changes — branch ${result.branchName} already matches the policy.`);
     }

package/commands/env.js

@@ -44,6 +44,28 @@ export const builder = (argv) => argv
 export const handler = (args) => args;
 /** Every OS-level env var name `@neondatabase/env` can emit, used only for reporting. */
 const NEON_VAR_NAMES = Object.values(NEON_ENV_VAR_KEYS).flatMap((group) => Object.values(group));
+/**
+ * The Neon env vars `env pull` *owns*, so it removes any that the branch no longer has when
+ * it reconciles the local `.env` (see {@link pull}). Scoped to the unambiguously Neon-named
+ * vars — the `NEON_*` aliases plus `DATABASE_URL[_UNPOOLED]` — so switching a working
+ * directory to a project/branch without Auth / the Data API drops the now-stale
+ * `NEON_AUTH_*` / `NEON_DATA_API_*` lines instead of leaving credentials for features that
+ * aren't enabled.
+ *
+ * Deliberately **excludes** the storage / AI Gateway vars Neon projects onto third-party SDK
+ * names (`AWS_*`, `OPENAI_*`): those collide with credentials a user may set by hand, so
+ * `env pull` only ever writes them, never prunes them. (Their Neon-branded siblings —
+ * `NEON_STORAGE_*` / `NEON_AI_GATEWAY_*` — are owned and pruned.)
+ */
+const NEON_OWNED_ENV_KEYS = [
+    ...Object.values(NEON_ENV_VAR_KEYS.postgres),
+    ...Object.values(NEON_ENV_VAR_KEYS.auth),
+    ...Object.values(NEON_ENV_VAR_KEYS.dataApi),
+    NEON_ENV_VAR_KEYS.storage.regionNeon,
+    NEON_ENV_VAR_KEYS.storage.forcePathStyle,
+    NEON_ENV_VAR_KEYS.aiGateway.neonToken,
+    NEON_ENV_VAR_KEYS.aiGateway.neonBaseUrl,
+];
 export const pull = async (props, opts = {}) => {
     const cwd = props.cwd ?? process.cwd();
     const branch = await resolveBranchRef(props);
@@ -75,8 +97,16 @@ export const pull = async (props, opts = {}) => {
             'enabled Auth / Data API).');
         return { status: 'empty' };
     }
-    const { written } = mergeEnvFile(targetPath, neonVars);
+    // Reconcile rather than blindly merge: write the branch's current Neon vars and prune any
+    // Neon-owned vars the branch no longer has (e.g. NEON_AUTH_* / NEON_DATA_API_* carried over
+    // from a previous project/branch). Non-Neon lines are always preserved.
+    const { written, removed } = mergeEnvFile(targetPath, neonVars, {
+        managedKeys: NEON_OWNED_ENV_KEYS,
+    });
     log.info('Pulled %d Neon variable%s into %s: %s', written.length, written.length === 1 ? '' : 's', targetPath, written.join(', '));
+    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(', '));
+    }
     return { status: 'written', written, file: targetPath };
 };
 /**

package/commands/functions.js

@@ -14,6 +14,16 @@ const FUNCTION_FIELDS = [
     'invocation_url',
     'created_at',
 ];
+const FUNCTIONS_LIST_LIMIT = 100;
+// Table columns for `functions list`. `status` is a derived field (the
+// table writer reads flat fields only): the current deployment's status.
+const LIST_TABLE_FIELDS = [
+    'slug',
+    'name',
+    'status',
+    'invocation_url',
+    'created_at',
+];
 const DEPLOYMENT_FIELDS = [
     'id',
     'status',
@@ -45,14 +55,14 @@ const ENTRY_CANDIDATES = ['index.ts', 'index.mjs', 'index.js'];
 // Overridable so tests can poll fast; defaults to 2s in real use.
 const POLL_INTERVAL_MS = Number(process.env.NEON_FUNCTIONS_POLL_INTERVAL_MS) || 2000;
 // Upper bound on --wait polling so the CLI never hangs (e.g. if our deployment
-// never becomes active_deployment). Overridable so tests can time out fast;
+// never shows up as current_deployment). Overridable so tests can time out fast;
 // defaults to 10 minutes in real use.
 const POLL_TIMEOUT_MS = Number(process.env.NEON_FUNCTIONS_POLL_TIMEOUT_MS) || 600000;
-export const command = 'functions';
+export const command = 'function';
 export const describe = 'Manage Neon Functions';
-export const aliases = ['function'];
+export const aliases = ['functions'];
 export const builder = (argv) => argv
-    .usage('$0 functions <sub-command> [options]')
+    .usage('$0 function <sub-command> [options]')
     .options({
     'project-id': {
         describe: 'Project ID',
@@ -137,7 +147,7 @@ const parseEnv = (entries) => {
     }
     return JSON.stringify(map);
 };
-const statusHint = (slug, projectId, branchId) => `Check status with: neonctl functions get ${slug} --project-id ${projectId} --branch ${branchId}`;
+const statusHint = (slug, projectId, branchId) => `Check status with: neonctl function get ${slug} --project-id ${projectId} --branch ${branchId}`;
 // Emit the resolved deployment together with the function's invocation_url, so the
 // deploy output shows where the function is reachable (not just the deployment id).
 const emitDeployResult = (props, deployment, fn) => {
@@ -165,7 +175,7 @@ const deploy = async (props) => {
         props.runtime !== undefined;
     if (!hasOption) {
         throw new Error('Provide at least one option to deploy, e.g. --src or --env. ' +
-            'See: neonctl functions deploy --help.');
+            'See: neonctl function deploy --help.');
     }
     // Cheap, offline validation first - fail before any network round-trip.
     if (!SLUG_PATTERN.test(props.slug)) {
@@ -188,12 +198,12 @@ const deploy = async (props) => {
     // Bundle before any network round-trip so a bundling failure fails fast.
     const zip = zipBundle(await bundleEntry(source));
     const branchId = await branchIdFromProps(props);
-    // Snapshot the active version before deploy so we can detect the new one
-    // afterward. A missing function (404) or no active version → undefined.
+    // Snapshot the current version before deploy so we can detect the new one
+    // afterward. A missing function (404) or no deployment yet → undefined.
     let before;
     try {
         const fn = await getFunction(props.apiClient, props.projectId, branchId, props.slug);
-        before = fn.active_deployment?.id;
+        before = fn.current_deployment?.id;
     }
     catch (err) {
         if (!(isAxiosError(err) && err.response?.status === 404))
@@ -213,12 +223,12 @@ const deploy = async (props) => {
     };
     process.once('SIGINT', onSignal);
     process.once('SIGTERM', onSignal);
-    // Poll until a NEW active version appears (id greater than the snapshot, or
+    // Poll until a NEW version appears (id greater than the snapshot, or
     // any version if there was none). --no-wait stops there; --wait stops at a
     // terminal status. Bounded by POLL_TIMEOUT_MS so it never hangs.
     let resolved;
     // The function carries the invocation_url; keep the whole record (not just its
-    // active_deployment) so we can surface that URL on success.
+    // current_deployment) so we can surface that URL on success.
     let resolvedFn;
     const deadline = Date.now() + POLL_TIMEOUT_MS;
     try {
@@ -237,7 +247,7 @@ const deploy = async (props) => {
                     continue;
                 throw err;
             }
-            const dep = fn.active_deployment;
+            const dep = fn.current_deployment;
             const isNew = dep !== undefined && (before === undefined || dep.id > before);
             if (isNew && dep) {
                 resolved = dep;
@@ -290,12 +300,31 @@ const get = async (props) => {
         fields: FUNCTION_FIELDS,
         title: 'function',
     });
-    if (fn.active_deployment) {
-        out.write(fn.active_deployment, {
+    const current = fn.current_deployment;
+    const active = fn.active_deployment;
+    if (current && active && current.id === active.id) {
+        out.write(current, {
             fields: DEPLOYMENT_FIELDS,
-            title: 'active deployment',
+            title: 'deployment (current, active)',
         });
-        writeDeploymentErrorSection(out, fn.active_deployment);
+        writeDeploymentErrorSection(out, current);
+    }
+    else {
+        if (current) {
+            out.write(current, {
+                fields: DEPLOYMENT_FIELDS,
+                title: 'current deployment',
+            });
+            // The failure reason is shown only for the current deployment;
+            // the active one completed successfully by definition.
+            writeDeploymentErrorSection(out, current);
+        }
+        if (active) {
+            out.write(active, {
+                fields: DEPLOYMENT_FIELDS,
+                title: 'active deployment',
+            });
+        }
     }
     if (props.listEnvVariables) {
         out.write((fn.active_deployment?.environment ?? []).map((name) => ({ name })), {
@@ -321,13 +350,27 @@ const deleteFn = async (props) => {
 };
 const list = async (props) => {
     const branchId = await branchIdFromProps(props);
-    const functions = await listFunctions(props.apiClient, props.projectId, branchId);
+    const functions = [];
+    let cursor;
+    for (;;) {
+        const page = await listFunctions(props.apiClient, props.projectId, branchId, { cursor, limit: FUNCTIONS_LIST_LIMIT });
+        functions.push(...page.functions);
+        log.debug('Got %d functions, next cursor: %s', page.functions.length, page.next);
+        // A server echoing the same cursor would loop forever; treat it as
+        // the end of the list.
+        if (!page.next || page.next === cursor)
+            break;
+        cursor = page.next;
+    }
     if (props.output === 'json' || props.output === 'yaml') {
         writer(props).end(functions, { fields: FUNCTION_FIELDS });
         return;
     }
-    writer(props).end(functions, {
-        fields: FUNCTION_FIELDS,
+    writer(props).end(functions.map((fn) => ({
+        ...fn,
+        status: fn.current_deployment?.status ?? '',
+    })), {
+        fields: LIST_TABLE_FIELDS,
         emptyMessage: 'No functions found on this branch.',
     });
 };

package/env_file.js

@@ -16,35 +16,47 @@ export const resolveEnvFilePath = (cwd, file) => {
  * Merge `updates` into the dotenv content at `path`, preserving every other line
  * (comments, blank lines, unrelated keys) and the file's existing order. Keys present in
  * both are updated in place; keys only in `updates` are appended. A non-existent file is
- * treated as empty. Returns the list of keys that were written (for reporting).
+ * treated as empty. When `managedKeys` is given, any owned key on disk that is absent from
+ * `updates` is removed. Returns the keys written and the (managed) keys removed.
  */
-export const mergeEnvFile = (path, updates) => {
+export const mergeEnvFile = (path, updates, options = {}) => {
     const original = existsSync(path) ? readFileSync(path, 'utf8') : '';
-    const { content, written } = mergeEnvContent(original, updates);
+    const { content, written, removed } = mergeEnvContent(original, updates, options);
     writeFileSync(path, content);
-    return { written };
+    return { written, removed };
 };
 /**
  * Pure core of {@link mergeEnvFile}: takes the current file content and the updates, and
- * returns the new content plus which keys were written. Kept side-effect-free so it can be
- * unit-tested without touching the filesystem.
+ * returns the new content plus which keys were written / removed. Kept side-effect-free so
+ * it can be unit-tested without touching the filesystem.
  */
-export const mergeEnvContent = (original, updates) => {
+export const mergeEnvContent = (original, updates, options = {}) => {
     const keys = Object.keys(updates);
-    if (keys.length === 0)
-        return { content: original, written: [] };
+    // Owned keys the current pull did not produce: stale Neon-managed vars to prune. Anything
+    // not in `managedKeys` is always kept, so a user's own lines are never removed.
+    const stale = new Set([...(options.managedKeys ?? [])].filter((key) => !(key in updates)));
+    if (keys.length === 0 && stale.size === 0) {
+        return { content: original, written: [], removed: [] };
+    }
     const remaining = new Set(keys);
+    const removed = [];
     const lines = original === '' ? [] : original.split('\n');
-    // Update keys in place where they already appear, so their position and any surrounding
-    // comments are preserved.
-    const updatedLines = lines.map((line) => {
+    // Walk the file: drop stale owned lines, update existing keys in place (so their position
+    // and any surrounding comments are preserved), and pass everything else through untouched.
+    const updatedLines = [];
+    for (const line of lines) {
         const key = parseKey(line);
+        if (key !== null && stale.has(key)) {
+            removed.push(key);
+            continue;
+        }
         if (key !== null && remaining.has(key)) {
             remaining.delete(key);
-            return formatLine(key, updates[key]);
+            updatedLines.push(formatLine(key, updates[key]));
+            continue;
         }
-        return line;
-    });
+        updatedLines.push(line);
+    }
     // Append keys that weren't already present, in the order they were given.
     const appended = keys
         .filter((key) => remaining.has(key))
@@ -55,6 +67,7 @@ export const mergeEnvContent = (original, updates) => {
         // A dotenv file ends with a trailing newline.
         content: content === '' ? '' : `${content}\n`,
         written: keys,
+        removed,
     };
 };
 /**

package/functions_api.js

@@ -1,13 +1,14 @@
 import { ContentType } from '@neondatabase/api-client';
 const functionsPath = (projectId, branchId) => `/projects/${encodeURIComponent(projectId)}/branches/${encodeURIComponent(branchId)}/functions`;
-export const listFunctions = async (apiClient, projectId, branchId) => {
+export const listFunctions = async (apiClient, projectId, branchId, { cursor, limit } = {}) => {
     const { data } = await apiClient.request({
         path: functionsPath(projectId, branchId),
         method: 'GET',
+        query: { cursor, limit },
         secure: true,
         format: 'json',
     });
-    return data.functions;
+    return { functions: data.functions ?? [], next: data.pagination?.next };
 };
 export const getFunction = async (apiClient, projectId, branchId, slug) => {
     const { data } = await apiClient.request({

package/package.json

@@ -5,7 +5,7 @@
     "url": "git+ssh://git@github.com/neondatabase/neonctl.git"
   },
   "type": "module",
-  "version": "2.26.2",
+  "version": "2.26.3",
   "description": "CLI tool for NeonDB Cloud management",
   "main": "index.js",
   "author": "NeonDB",
@@ -59,9 +59,9 @@
   "dependencies": {
     "@hono/node-server": "2.0.4",
     "@neondatabase/api-client": "2.7.1",
-    "@neondatabase/config": "0.7.1",
-    "@neondatabase/config-runtime": "0.7.1",
-    "@neondatabase/env": "0.5.1",
+    "@neondatabase/config": "0.7.2",
+    "@neondatabase/config-runtime": "0.7.2",
+    "@neondatabase/env": "0.5.2",
     "@segment/analytics-node": "1.3.0",
     "axios": "1.7.2",
     "axios-debug-log": "1.0.0",

package/test_utils/fixtures.js

@@ -41,7 +41,7 @@ export const test = originalTest.extend({
                 '--api-host',
                 `http://localhost:${server.address().port}`,
                 '--output',
-                options.outputTable ? 'table' : 'yaml',
+                options.output ?? (options.outputTable ? 'table' : 'yaml'),
                 '--api-key',
                 'test-key',
                 '--no-analytics',