neonctl 2.24.0 → 2.24.2

package/README.md

@@ -140,6 +140,8 @@ The Neon CLI supports autocompletion, which you can configure in a few easy step
 
 `neonctl link` is a Vercel-style command that binds the current directory to a Neon project. It picks (or creates) an organization, picks (or creates) a project, resolves the project's default branch, and writes a `.neon` file with `{ "orgId", "projectId", "branchId" }`. Subsequent commands run in this directory (or any sub-directory) automatically pick up that context.
 
+Once the branch is pinned, `link` also runs [`env pull`](#env-pull) for you so the branch's Neon env vars (`DATABASE_URL`, …) land in a local `.env` and the project is immediately ready for local dev. Pass `--no-env-pull` to skip it (for example when injecting env at runtime with `neon-env run` or `neonctl dev`).
+
 There are three modes:
 
 **Interactive (default)** — guided prompts for humans:
@@ -157,6 +159,16 @@ Linked .neon:
   branchId:  br-main-branch-87654321
 ```
 
+When you link an **existing** project that has more than one branch, `link` adds a final
+step to pick which branch to pin — the same `＋ Create a new branch…` + list selector used by
+`neonctl checkout` (a single-branch project is pinned automatically, no prompt):
+
+```bash
+? Which organization would you like to link? › Personal Org (org-abc123)
+? Which project would you like to link? › my-app (polished-snowflake-12345678)
+? Which branch would you like to link? › [default] main (br-main-branch-87654321)
+```
+
 **Non-interactive (flags or `--params` JSON)** — for scripts and CI:
 
 ```bash
@@ -265,6 +277,24 @@ $ cat .neon
 }
 ```
 
+After pinning the branch, `checkout` also runs [`env pull`](#env-pull) by default, so the branch's Neon env vars are written to your local `.env` and you can start building right away — the branch-first loop is just `link` + `checkout`. Pass `--no-env-pull` to skip it (for example when env is injected at runtime via `neon-env run` / `neonctl dev`, or to keep secrets out of the working tree). A pull failure never undoes the checkout: the branch stays pinned and the failure is surfaced as a warning pointing you at `neonctl env pull` (or `neonctl deploy` if a `neon.ts`-declared service is missing).
+
+### env pull
+
+`env pull` writes the linked branch's Neon environment variables into a local dotenv file: an existing `.env` if you have one, otherwise `.env.local` (override with `--file <path>`). Only Neon-managed keys (`DATABASE_URL`, `DATABASE_URL_UNPOOLED`, and the Neon Auth / Data API URLs when those services are enabled) are written; any other lines in the file are preserved. The branch comes from the closest `.neon` file, so no `--branch` is needed (pass `--branch <id|name>` to target another branch).
+
+`link` and `checkout` invoke `env pull` automatically (see above), so you usually only run it by hand to refresh vars or to pull a different branch into a specific file:
+
+```bash
+# Refresh the linked branch's vars in place
+neonctl env pull
+
+# Pull a specific branch into a specific file
+neonctl env pull --branch preview --file .env.preview
+```
+
+If you'd rather not keep env vars on disk, inject them at runtime instead with `neon-env run -- <your dev command>` (from `@neondatabase/env`) or `neonctl dev`, and pass `--no-env-pull` to `link` / `checkout`.
+
 **Where `.neon` lives**: `link` (and `set-context`) write `.neon` into the **current working directory** by default. If an existing `.neon` is found in any parent directory, that file is reused — so commands run from a sub-directory of a linked project still pick up the project's context. To pin the location explicitly, pass `--context-file <path>`.
 
 **`.gitignore` scaffolding**: when `.neon` is **created** for the first time, the CLI also makes sure a `.gitignore` sits alongside it listing `.neon`. If `.gitignore` doesn't exist it's created with a single `.neon` line; if it does exist, `.neon` is appended only when missing (no duplicates, your other entries are left alone). On subsequent updates to an existing `.neon`, `.gitignore` is left untouched — so if you deliberately un-ignore `.neon` (e.g. to commit shared context), the entry is not re-added on every command.
@@ -328,25 +358,27 @@ Function deploys declared under `preview.functions` are bundled by neonctl's own
 
 ## Commands
 
-| Command                                                                    | Subcommands                                                                                 | Description                    |
-| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------ |
-| [auth](https://neon.com/docs/reference/cli-auth)                           |                                                                                             | Authenticate                   |
-| [projects](https://neon.com/docs/reference/cli-projects)                   | `list`, `create`, `update`, `delete`, `get`                                                 | Manage projects                |
-| [ip-allow](https://neon.com/docs/reference/cli-ip-allow)                   | `list`, `add`, `remove`, `reset`                                                            | Manage IP Allow                |
-| [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          |
-| [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          |
-| psql                                                                       |                                                                                             | Connect to a database via psql |
-| [set-context](https://neon.com/docs/reference/cli-set-context)             |                                                                                             | Set context for session        |
-| checkout                                                                   |                                                                                             | Pin a branch in `.neon`        |
-| [link](https://neon.com/docs/reference/cli-link)                           |                                                                                             | Link a directory to a project  |
-| config                                                                     | `status`, `plan`, `apply`                                                                   | Drive a branch from `neon.ts`  |
-| deploy                                                                     |                                                                                             | Alias for `config apply`       |
-| [completion](https://neon.com/docs/reference/cli-completion)               |                                                                                             | Generate a completion script   |
+| Command                                                                    | Subcommands                                                                                    | Description                      |
+| -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------- |
+| [auth](https://neon.com/docs/reference/cli-auth)                           |                                                                                                | Authenticate                     |
+| [projects](https://neon.com/docs/reference/cli-projects)                   | `list`, `create`, `update`, `delete`, `get`                                                    | Manage projects                  |
+| [ip-allow](https://neon.com/docs/reference/cli-ip-allow)                   | `list`, `add`, `remove`, `reset`                                                               | Manage IP Allow                  |
+| [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            |
+| [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            |
+| psql                                                                       |                                                                                                | Connect to a database via psql   |
+| [set-context](https://neon.com/docs/reference/cli-set-context)             |                                                                                                | Set context for session          |
+| env                                                                        | `pull`                                                                                         | Manage a branch's env vars       |
+| checkout                                                                   |                                                                                                | Pin a branch in `.neon`          |
+| [link](https://neon.com/docs/reference/cli-link)                           |                                                                                                | Link a directory to a project    |
+| config                                                                     | `status`, `plan`, `apply`                                                                      | Drive a branch from `neon.ts`    |
+| deploy                                                                     |                                                                                                | Alias for `config apply`         |
+| bucket                                                                     | `create`, `list`, `delete`, `object list`, `object get`, `object delete` (incl. `--recursive`) | Manage buckets and their objects |
+| [completion](https://neon.com/docs/reference/cli-completion)               |                                                                                                | Generate a completion script     |
 
 ## Global options
 

package/commands/branches.js

@@ -1,4 +1,5 @@
 import { EndpointType } from '@neondatabase/api-client';
+import { readContextFile } from '../context.js';
 import { writer } from '../writer.js';
 import { branchCreateRequest } from '../parameters.gen.js';
 import { retryOnLock } from '../api.js';
@@ -219,25 +220,32 @@ const list = async (props) => {
     const { data: { branches, annotations }, } = await props.apiClient.listProjectBranches({
         projectId: props.projectId,
     });
+    // The branch pinned in the local context (.neon), so we can flag it as `[current]` — the
+    // one commands target by default and that `neonctl env pull` would read.
+    const currentBranchId = readContextFile(props.contextFile).branchId;
     writer(props).end(branches, {
         fields: BRANCH_FIELDS,
         renderColumns: {
             expires_at: (br) => br.expires_at || 'never',
+            // Word labels (not symbols) so they read clearly and match the existing `[anon]`.
             name: (br) => {
                 const annotation = annotations[br.id];
                 const isAnon = annotation?.value.anonymized;
-                const result = [];
+                const labels = [];
                 if (br.default) {
-                    result.push('✱');
+                    labels.push('[default]');
                 }
                 if (br.protected) {
-                    result.push('⛨');
+                    labels.push('[protected]');
                 }
                 if (isAnon) {
-                    result.push('[anon]');
+                    labels.push('[anon]');
                 }
-                result.push(br.name);
-                return result.join(' ');
+                if (currentBranchId !== undefined && br.id === currentBranchId) {
+                    labels.push('[current]');
+                }
+                labels.push(br.name);
+                return labels.join(' ');
             },
         },
     });

package/commands/bucket.js

@@ -0,0 +1,368 @@
+import { createWriteStream } from 'node:fs';
+import { unlink } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { isAxiosError } from 'axios';
+import { retryOnLock } from '../api.js';
+import { branchIdFromProps, fillSingleProject } from '../utils/enrichers.js';
+import { log } from '../log.js';
+import { writer } from '../writer.js';
+import { createProjectBranchBucket, listProjectBranchBuckets, deleteProjectBranchBucket, listProjectBranchBucketObjects, getProjectBranchBucketObject, deleteProjectBranchBucketObject, deleteProjectBranchBucketObjectsByPrefix, } from '../storage_api.js';
+const OBJECT_FIELDS = ['key', 'size', 'last_modified', 'etag'];
+const BUCKET_FIELDS = ['name', 'access_level'];
+const ACCESS_LEVELS = ['private', 'public_read'];
+// Ambient scope shared by every bucket sub-command. The bucket name (and the
+// object key/prefix) is always a positional, never a flag.
+const scopeOptions = {
+    'project-id': {
+        describe: 'Project ID',
+        type: 'string',
+    },
+    branch: {
+        describe: 'Branch ID or name',
+        type: 'string',
+    },
+};
+// Split an object target into its bucket and the remainder (key or prefix) on
+// the FIRST `/`. Bucket names are DNS-safe so they never contain a slash; the
+// remainder may contain further slashes and is returned verbatim. When the
+// target has no slash, `rest` is the empty string.
+export const splitBucketTarget = (target) => {
+    const slash = target.indexOf('/');
+    if (slash === -1) {
+        return { bucket: target, rest: '' };
+    }
+    return {
+        bucket: target.slice(0, slash),
+        rest: target.slice(slash + 1),
+    };
+};
+export const command = 'bucket';
+export const describe = 'Manage branch object-storage buckets and their objects';
+export const builder = (argv) => argv
+    .usage('$0 bucket <sub-command> [options]')
+    .options({
+    'project-id': {
+        describe: 'Project ID',
+        type: 'string',
+    },
+})
+    .middleware(fillSingleProject)
+    .command('create <name>', 'Create a bucket on a branch', (yargs) => yargs
+    .usage('$0 bucket create <name> [options]')
+    .positional('name', {
+    describe: 'The bucket name to create',
+    type: 'string',
+    demandOption: true,
+})
+    .options({
+    ...scopeOptions,
+    'access-level': {
+        describe: 'The visibility of the bucket',
+        type: 'string',
+        choices: ACCESS_LEVELS,
+        default: 'private',
+    },
+}), (args) => createBucket(args))
+    .command({
+    command: 'list',
+    aliases: ['ls'],
+    describe: 'List the buckets on a branch',
+    builder: (yargs) => yargs.usage('$0 bucket list [options]').options(scopeOptions),
+    handler: (args) => listBuckets(args),
+})
+    .command({
+    command: 'delete <name>',
+    aliases: ['rm'],
+    describe: 'Delete a bucket from a branch',
+    builder: (yargs) => yargs
+        .usage('$0 bucket delete <name> [options]')
+        .positional('name', {
+        describe: 'The bucket name to delete',
+        type: 'string',
+        demandOption: true,
+    })
+        .options(scopeOptions),
+    handler: (args) => deleteBucket(args),
+})
+    .command('object <sub-command>', 'List, download or delete objects in a bucket', (yargs) => yargs
+    .usage('$0 bucket object <sub-command> [options]')
+    .command({
+    command: 'list <target>',
+    aliases: ['ls'],
+    describe: 'List objects in a bucket',
+    builder: (yargs) => yargs
+        .usage('$0 bucket object list <bucket>[/<prefix>] [options]')
+        .positional('target', {
+        describe: 'The bucket to list, optionally with a key prefix: <bucket>[/<prefix>]',
+        type: 'string',
+        demandOption: true,
+    })
+        .options({
+        ...scopeOptions,
+        delimiter: {
+            describe: 'Collapse keys sharing a common prefix (e.g. "/") into folders',
+            type: 'string',
+        },
+        cursor: {
+            describe: 'Pagination cursor returned as next_cursor by a previous call',
+            type: 'string',
+        },
+        limit: {
+            describe: 'Maximum number of items (objects + folders) to return',
+            type: 'number',
+        },
+    }),
+    handler: (args) => listObjects(args),
+})
+    .command('get <target>', 'Download an object from a bucket to a local file', (yargs) => yargs
+    .usage('$0 bucket object get <bucket>/<key> [options]')
+    .positional('target', {
+    describe: 'The object to download: <bucket>/<key>',
+    type: 'string',
+    demandOption: true,
+})
+    .options({
+    ...scopeOptions,
+    file: {
+        describe: 'Path to write the downloaded object to (defaults to the object filename in the current directory)',
+        type: 'string',
+    },
+}), (args) => getObject(args))
+    .command({
+    command: 'delete <target>',
+    aliases: ['rm'],
+    describe: 'Delete an object, or every object under a prefix',
+    builder: (yargs) => yargs
+        .usage('$0 bucket object delete <bucket>/<key> [options]')
+        .positional('target', {
+        describe: 'The object to delete: <bucket>/<key>, or <bucket>/<prefix>/ with --recursive',
+        type: 'string',
+        demandOption: true,
+    })
+        .options({
+        ...scopeOptions,
+        recursive: {
+            describe: 'Delete every object under the given prefix. The prefix must end with "/"',
+            type: 'boolean',
+            default: false,
+        },
+    }),
+    handler: (args) => deleteObject(args),
+})
+    .demandCommand(1, '')
+    .strictCommands())
+    .demandCommand(1, '');
+export const handler = (args) => {
+    return args;
+};
+const createBucket = async (props) => {
+    const branchId = await branchIdFromProps(props);
+    const { data } = await retryOnLock(() => createProjectBranchBucket(props.apiClient, {
+        projectId: props.projectId,
+        branchId,
+        name: props.name,
+        accessLevel: props.accessLevel,
+    }));
+    log.info(`Bucket "${data.bucket.name}" (${data.bucket.access_level}) created on branch ${branchId}`);
+};
+const listBuckets = async (props) => {
+    const branchId = await branchIdFromProps(props);
+    const { data } = await listProjectBranchBuckets(props.apiClient, {
+        projectId: props.projectId,
+        branchId,
+    });
+    if (props.output === 'json' || props.output === 'yaml') {
+        writer(props).end(data.buckets, { fields: BUCKET_FIELDS });
+        return;
+    }
+    writer(props).end(data.buckets, {
+        fields: BUCKET_FIELDS,
+        title: 'buckets',
+        emptyMessage: 'No buckets found.',
+    });
+};
+const deleteBucket = async (props) => {
+    const branchId = await branchIdFromProps(props);
+    try {
+        await retryOnLock(() => deleteProjectBranchBucket(props.apiClient, {
+            projectId: props.projectId,
+            branchId,
+            bucketName: props.name,
+        }));
+    }
+    catch (err) {
+        if (isAxiosError(err) && err.response?.status === 404) {
+            throw new Error(`Bucket "${props.name}" not found on branch ${branchId}.`);
+        }
+        throw err;
+    }
+    log.info(`Bucket "${props.name}" deleted from branch ${branchId}`);
+};
+const listObjects = async (props) => {
+    const branchId = await branchIdFromProps(props);
+    const { bucket, rest } = splitBucketTarget(props.target);
+    const { data } = await listProjectBranchBucketObjects(props.apiClient, {
+        projectId: props.projectId,
+        branchId,
+        bucketName: bucket,
+        prefix: rest === '' ? undefined : rest,
+        delimiter: props.delimiter,
+        cursor: props.cursor,
+        limit: props.limit,
+    });
+    if (props.output === 'json' || props.output === 'yaml') {
+        writer(props).end(data, {
+            fields: ['folders', 'objects', 'prefix', 'next_cursor', 'is_truncated'],
+        });
+        return;
+    }
+    const w = writer(props);
+    if (data.folders.length > 0) {
+        w.write(data.folders.map((name) => ({ name })), { fields: ['name'], title: 'folders' });
+    }
+    w.write(data.objects, {
+        fields: OBJECT_FIELDS,
+        title: 'objects',
+        emptyMessage: 'No objects found.',
+    });
+    w.end();
+    if (data.is_truncated && data.next_cursor) {
+        log.info(`More results available. Re-run with --cursor ${data.next_cursor} to fetch the next page.`);
+    }
+};
+// Pull a filename out of a `Content-Disposition` header, falling back to the
+// last segment of the object key. Handles the plain and RFC 5987 (`filename*=`)
+// forms the download endpoint may emit.
+const filenameFromContentDisposition = (contentDisposition, key) => {
+    if (contentDisposition) {
+        const extended = /filename\*=(?:UTF-8'')?([^;]+)/i.exec(contentDisposition);
+        if (extended?.[1]) {
+            try {
+                return basename(decodeURIComponent(extended[1].trim()));
+            }
+            catch {
+                // Fall through to the plain form / key on malformed encoding.
+            }
+        }
+        const plain = /filename="?([^";]+)"?/i.exec(contentDisposition);
+        if (plain?.[1]) {
+            return basename(plain[1].trim());
+        }
+    }
+    return basename(key) || key;
+};
+// Pull the `message` field out of a server error body, returning undefined when
+// the body is absent, not an object, or carries no usable message.
+const serverErrorMessage = (body) => {
+    const message = body?.message;
+    return typeof message === 'string' && message.trim() !== ''
+        ? message
+        : undefined;
+};
+// Drain a streamed error body (the form an `octet-stream` download 404 takes)
+// and parse its `message`. Returns undefined on any read/parse failure so the
+// caller falls back to its default message.
+const streamErrorMessage = async (stream) => {
+    if (typeof stream?.[Symbol.asyncIterator] !== 'function') {
+        return undefined;
+    }
+    try {
+        const chunks = [];
+        for await (const chunk of stream) {
+            chunks.push(Buffer.from(chunk));
+        }
+        return serverErrorMessage(JSON.parse(Buffer.concat(chunks).toString()));
+    }
+    catch {
+        return undefined;
+    }
+};
+const objectNotFoundFallback = (key, bucket, branchId) => `Object "${key}" not found in bucket "${bucket}" on branch ${branchId}.`;
+// Prefer the server's error message when present so a missing bucket is not
+// misreported as a missing object; otherwise fall back to a clean default. Used
+// for the JSON (non-streamed) endpoints where the body is already parsed.
+const objectNotFoundMessage = (err, key, bucket, branchId) => {
+    if (isAxiosError(err)) {
+        const serverMessage = serverErrorMessage(err.response?.data);
+        if (serverMessage !== undefined) {
+            return serverMessage;
+        }
+    }
+    return objectNotFoundFallback(key, bucket, branchId);
+};
+const getObject = async (props) => {
+    const branchId = await branchIdFromProps(props);
+    const { bucket, rest: key } = splitBucketTarget(props.target);
+    if (key === '') {
+        throw new Error('Object target must be in the form <bucket>/<key>.');
+    }
+    let response;
+    try {
+        response = await getProjectBranchBucketObject(props.apiClient, {
+            projectId: props.projectId,
+            branchId,
+            bucketName: bucket,
+            objectKey: key,
+        });
+    }
+    catch (err) {
+        if (isAxiosError(err) && err.response?.status === 404) {
+            // The download response is a stream, so a 404 body arrives as a stream
+            // too; drain and parse it to recover the server's message (which
+            // distinguishes a missing bucket from a missing object).
+            const serverMessage = await streamErrorMessage(err.response.data);
+            throw new Error(serverMessage ?? objectNotFoundFallback(key, bucket, branchId));
+        }
+        throw err;
+    }
+    const contentDisposition = response.headers['content-disposition'];
+    const destination = props.file ?? filenameFromContentDisposition(contentDisposition, key);
+    try {
+        await pipeline(response.data, createWriteStream(destination));
+    }
+    catch (err) {
+        // Best-effort cleanup of the partial file before rethrowing.
+        await unlink(destination).catch(() => undefined);
+        throw err;
+    }
+    log.info(`Object "${key}" downloaded from bucket "${bucket}" on branch ${branchId} to ${destination}`);
+};
+const deleteObject = async (props) => {
+    const branchId = await branchIdFromProps(props);
+    const { bucket, rest } = splitBucketTarget(props.target);
+    if (props.recursive) {
+        if (rest === '') {
+            throw new Error('Recursive delete requires a non-empty prefix ending in "/".');
+        }
+        if (!rest.endsWith('/')) {
+            throw new Error(`Recursive delete requires a prefix ending in "/" (got "${rest}").`);
+        }
+        const { data } = await retryOnLock(() => deleteProjectBranchBucketObjectsByPrefix(props.apiClient, {
+            projectId: props.projectId,
+            branchId,
+            bucketName: bucket,
+            prefix: rest,
+        }));
+        log.info(`Deleted ${data.deleted} object(s) under prefix "${rest}" from bucket "${bucket}" on branch ${branchId}`);
+        return;
+    }
+    if (rest === '') {
+        throw new Error('Object target must be in the form <bucket>/<key>.');
+    }
+    try {
+        await retryOnLock(() => deleteProjectBranchBucketObject(props.apiClient, {
+            projectId: props.projectId,
+            branchId,
+            bucketName: bucket,
+            objectKey: rest,
+        }));
+    }
+    catch (err) {
+        if (isAxiosError(err) && err.response?.status === 404) {
+            throw new Error(objectNotFoundMessage(err, rest, bucket, branchId));
+        }
+        throw err;
+    }
+    log.info(`Object "${rest}" deleted from bucket "${bucket}" on branch ${branchId}`);
+};