neonctl 2.26.1 → 2.26.3

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.1",
+  "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",
@@ -71,7 +71,7 @@
     "cliui": "8.0.1",
     "diff": "5.2.0",
     "fflate": "^0.8.3",
-    "neon-init": "0.16.1",
+    "neon-init": "0.16.3",
     "open": "10.1.0",
     "openid-client": "6.8.1",
     "pg-protocol": "^1.14.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',

package/utils/bootstrap.js

@@ -1,7 +1,13 @@
 import axios, { isAxiosError } from 'axios';
+import { gunzipSync } from 'fflate';
 import YAML from 'yaml';
 import { log } from '../log.js';
-/** Hardcoded fallback used when the remote manifest cannot be fetched. */
+/**
+ * Hardcoded fallback used when every remote manifest source is unreachable.
+ * Kept in sync with `neondatabase/examples/bootstrap.yaml` (the source of
+ * truth) so that, even fully offline from the manifest, the picker still offers
+ * the full set of starters rather than a single template.
+ */
 export const FALLBACK_TEMPLATES = [
     {
         id: 'hono',
@@ -15,25 +21,44 @@ export const FALLBACK_TEMPLATES = [
             subdir: 'with-hono',
         },
     },
+    {
+        id: 'ai-sdk',
+        title: 'AI SDK agent (AI Gateway, object storage, Drizzle) on Neon Functions',
+        description: 'A Vercel AI SDK agent on Neon Functions: streams chat through the Neon AI Gateway, generates an image with OpenAI image generation, and stores it in Neon object storage indexed in Postgres via Drizzle.',
+        services: ['Postgres', 'Functions', 'Object Storage', 'AI Gateway'],
+        source: {
+            owner: 'neondatabase',
+            repo: 'examples',
+            ref: 'main',
+            subdir: 'with-ai-sdk',
+        },
+    },
+    {
+        id: 'mastra',
+        title: 'Mastra personal agent (AI Gateway, Mastra Memory) on Neon Functions',
+        description: 'A Mastra personal-assistant agent on Neon Functions: streams chat through the Neon AI Gateway and uses Mastra Memory — backed by Neon Postgres — to remember the user across conversation threads via resource-scoped working memory.',
+        services: ['Postgres', 'Functions', 'AI Gateway'],
+        source: {
+            owner: 'neondatabase',
+            repo: 'examples',
+            ref: 'main',
+            subdir: 'with-mastra',
+        },
+    },
 ];
 export const templateIds = (templates) => templates.map((t) => t.id).join(', ');
 export const findTemplate = (templates, id) => templates.find((t) => t.id === id);
-// Hosts are overridable so the e2e tests can point the downloader at a local
-// server (the same trick `--api-host` uses to redirect the Neon API in tests).
-// The defaults hit public GitHub; copying a public template needs no auth.
-const githubApiBase = () => process.env.NEON_BOOTSTRAP_GITHUB_API ?? 'https://api.github.com';
-const githubRawBase = () => process.env.NEON_BOOTSTRAP_GITHUB_RAW ?? 'https://raw.githubusercontent.com';
 const githubToken = () => process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN ?? '';
-const apiHeaders = () => ({
-    Accept: 'application/vnd.github+json',
-    'X-GitHub-Api-Version': '2022-11-28',
-    'User-Agent': 'neonctl',
-    ...(githubToken() ? { Authorization: `Bearer ${githubToken()}` } : {}),
-});
-const rawHeaders = () => ({
+// A token is never required for public templates, but we forward it when
+// present so the same code path works behind proxies that authenticate, and
+// (in future) for private template repos.
+const downloadHeaders = () => ({
     'User-Agent': 'neonctl',
     ...(githubToken() ? { Authorization: `Bearer ${githubToken()}` } : {}),
 });
+// The codeload host is overridable so the e2e tests can point the downloader at
+// a local server (the same trick `--api-host` uses to redirect the Neon API).
+const codeloadBase = () => process.env.NEON_BOOTSTRAP_GITHUB_CODELOAD ?? 'https://codeload.github.com';
 const isRecord = (value) => typeof value === 'object' && value !== null;
 /**
  * Normalize a manifest entry's `services` into a clean string list. Tolerant by
@@ -51,8 +76,18 @@ const parseServices = (value) => {
 // ---------------------------------------------------------------------------
 // Remote template manifest
 // ---------------------------------------------------------------------------
-const manifestUrl = () => process.env.NEON_BOOTSTRAP_MANIFEST_URL ??
-    `${githubRawBase()}/neondatabase/examples/main/bootstrap.yaml`;
+// Primary manifest host is neon.com (CDN-backed, no GitHub rate limiting),
+// with the raw GitHub copy as a fallback and the hardcoded list as the last
+// resort. A single env override (used by tests) short-circuits the chain.
+const NEON_MANIFEST_URL = 'https://neon.com/bootstrap/templates.yaml';
+const GITHUB_RAW_MANIFEST_URL = 'https://raw.githubusercontent.com/neondatabase/examples/main/bootstrap.yaml';
+const manifestUrls = () => {
+    const override = process.env.NEON_BOOTSTRAP_MANIFEST_URL;
+    if (override) {
+        return [override];
+    }
+    return [NEON_MANIFEST_URL, GITHUB_RAW_MANIFEST_URL];
+};
 export const parseManifest = (text) => {
     const data = YAML.parse(text);
     if (!isRecord(data) || !Array.isArray(data.templates)) {
@@ -90,154 +125,240 @@ export const parseManifest = (text) => {
     return templates;
 };
 /**
- * Fetch the template manifest from the remote `bootstrap.yaml` in the
- * neondatabase/examples repo. Falls back to the hardcoded list on any error
- * so the command never fails just because GitHub is unreachable.
+ * Fetch the template manifest, trying each source in {@link manifestUrls} in
+ * order and returning the first that yields a non-empty template list. Falls
+ * back to the hardcoded list when every source is unreachable or empty, so the
+ * command never fails just because a host is down.
  */
 export const fetchTemplates = async () => {
-    const url = manifestUrl();
-    try {
-        const res = await axios.get(url, {
-            responseType: 'text',
-            headers: rawHeaders(),
-            timeout: 10000,
-        });
-        const templates = parseManifest(res.data);
-        if (templates.length === 0) {
-            log.warning('Remote bootstrap manifest at %s contained no templates; using built-in defaults.', url);
-            return FALLBACK_TEMPLATES;
+    for (const url of manifestUrls()) {
+        try {
+            const res = await axios.get(url, {
+                responseType: 'text',
+                headers: downloadHeaders(),
+                timeout: 10000,
+            });
+            const templates = parseManifest(res.data);
+            if (templates.length > 0) {
+                return templates;
+            }
+            log.debug('bootstrap: manifest at %s contained no templates; trying next source.', url);
+        }
+        catch (err) {
+            log.debug('bootstrap: failed to fetch manifest from %s: %s — trying next source.', url, err instanceof Error ? err.message : String(err));
         }
-        return templates;
-    }
-    catch (err) {
-        log.debug('bootstrap: failed to fetch manifest from %s: %s — using built-in defaults.', url, err instanceof Error ? err.message : String(err));
-        return FALLBACK_TEMPLATES;
     }
+    log.debug('bootstrap: all manifest sources exhausted; using built-in defaults.');
+    return FALLBACK_TEMPLATES;
 };
-const malformed = (what) => new Error(`Unexpected GitHub API response while resolving ${what}.`);
-const parseCommit = (data) => {
-    if (!isRecord(data) || typeof data.sha !== 'string') {
-        throw malformed('the template commit');
-    }
-    const { commit } = data;
-    if (!isRecord(commit) ||
-        !isRecord(commit.tree) ||
-        typeof commit.tree.sha !== 'string') {
-        throw malformed('the template tree');
-    }
-    return { commitSha: data.sha, treeSha: commit.tree.sha };
+const TAR_BLOCK = 512;
+const readTarString = (buf, offset, length) => {
+    let end = offset;
+    const max = offset + length;
+    while (end < max && buf[end] !== 0) {
+        end++;
+    }
+    return buf.toString('utf8', offset, end);
 };
-const parseTree = (data) => {
-    if (!isRecord(data) || !Array.isArray(data.tree)) {
-        throw malformed('the template file tree');
+const readTarOctal = (buf, offset, length) => {
+    const text = readTarString(buf, offset, length).trim();
+    if (text === '') {
+        return 0;
     }
-    const tree = [];
-    for (const item of data.tree) {
-        if (isRecord(item) &&
-            typeof item.path === 'string' &&
-            typeof item.mode === 'string' &&
-            typeof item.type === 'string') {
-            tree.push({ path: item.path, mode: item.mode, type: item.type });
+    const value = parseInt(text, 8);
+    return Number.isNaN(value) ? 0 : value;
+};
+const isZeroBlock = (buf, offset) => {
+    for (let i = offset; i < offset + TAR_BLOCK; i++) {
+        if (buf[i] !== 0) {
+            return false;
         }
     }
-    return { truncated: data.truncated === true, tree };
+    return true;
 };
-const friendlyGithubError = (err, url) => {
-    if (isAxiosError(err)) {
-        const status = err.response?.status;
-        if (status === 404) {
-            return new Error(`GitHub returned 404 for ${url}. The template repo, ref, or subdirectory may have moved.`);
+/**
+ * Parse pax extended-header records ("<len> <key>=<value>\n"). GitHub uses
+ * these for the global header and for any path that doesn't fit the legacy
+ * 100-byte name field, so we must honor at least `path` and `linkpath`.
+ */
+const parsePaxRecords = (data) => {
+    const records = {};
+    let pos = 0;
+    const text = data.toString('utf8');
+    while (pos < text.length) {
+        const space = text.indexOf(' ', pos);
+        if (space === -1) {
+            break;
+        }
+        const len = parseInt(text.slice(pos, space), 10);
+        if (Number.isNaN(len) || len <= 0) {
+            break;
         }
-        if (status === 403 &&
-            err.response?.headers['x-ratelimit-remaining'] === '0') {
-            return new Error('GitHub API rate limit exceeded. Set a GITHUB_TOKEN environment variable to raise the limit, then retry.');
+        const record = text.slice(space + 1, pos + len - 1); // drop trailing "\n"
+        const eq = record.indexOf('=');
+        if (eq !== -1) {
+            records[record.slice(0, eq)] = record.slice(eq + 1);
         }
+        pos += len;
     }
-    return err instanceof Error ? err : new Error(String(err));
+    return records;
 };
-const getJson = async (url) => {
-    try {
-        const res = await axios.get(url, { headers: apiHeaders() });
-        return res.data;
-    }
-    catch (err) {
-        throw friendlyGithubError(err, url);
+/**
+ * Decode a (decompressed) tar archive into its file/symlink entries. Pure and
+ * dependency-free so it can be unit tested without touching the network.
+ * Handles the ustar `prefix` field, pax extended headers (type 'x'/'g'), and
+ * GNU long-name/long-link headers (type 'L'/'K') so deep template paths and
+ * long symlink targets round-trip correctly.
+ */
+export const parseTar = (buf) => {
+    const entries = [];
+    // Overrides carried from a preceding pax/GNU header to the next real entry.
+    let overridePath;
+    let overrideLink;
+    let offset = 0;
+    while (offset + TAR_BLOCK <= buf.length) {
+        if (isZeroBlock(buf, offset)) {
+            break;
+        }
+        let name = readTarString(buf, offset, 100);
+        const mode = readTarOctal(buf, offset + 100, 8);
+        const size = readTarOctal(buf, offset + 124, 12);
+        const typeByte = buf[offset + 156];
+        const type = typeByte === 0 ? '0' : String.fromCharCode(typeByte);
+        let linkname = readTarString(buf, offset + 157, 100);
+        const magic = readTarString(buf, offset + 257, 6);
+        if (magic.startsWith('ustar')) {
+            const prefix = readTarString(buf, offset + 345, 155);
+            if (prefix !== '') {
+                name = `${prefix}/${name}`;
+            }
+        }
+        offset += TAR_BLOCK;
+        const data = buf.subarray(offset, offset + size);
+        offset += Math.ceil(size / TAR_BLOCK) * TAR_BLOCK;
+        if (type === 'x') {
+            const records = parsePaxRecords(data);
+            if (records.path !== undefined) {
+                overridePath = records.path;
+            }
+            if (records.linkpath !== undefined) {
+                overrideLink = records.linkpath;
+            }
+            continue;
+        }
+        if (type === 'g') {
+            // Global pax header (e.g. GitHub's comment block): not per-entry state.
+            continue;
+        }
+        if (type === 'L' || type === 'K') {
+            const longValue = data.toString('utf8').replace(/\0+$/, '');
+            if (type === 'L') {
+                overridePath = longValue;
+            }
+            else {
+                overrideLink = longValue;
+            }
+            continue;
+        }
+        if (overridePath !== undefined) {
+            name = overridePath;
+        }
+        if (overrideLink !== undefined) {
+            linkname = overrideLink;
+        }
+        overridePath = undefined;
+        overrideLink = undefined;
+        entries.push({ name, type, mode, linkname, data: Buffer.from(data) });
     }
+    return entries;
 };
 /**
- * Map a flat (recursive) git tree to the entries under `subdir`, with the
- * `subdir/` prefix stripped from each `path`. Pure so it can be unit tested
- * without touching the network. Directory nodes are dropped — git never
- * stores empty directories, and writing files re-creates their parents.
+ * Map decoded tar entries to the files under `subdir`, with the top-level
+ * archive directory and the `subdir/` prefix stripped from each path. Pure so
+ * it can be unit tested. Directory and other non-regular entries are dropped —
+ * writing files re-creates their parent directories.
  */
-export const selectSubtreeEntries = (tree, subdir) => {
-    const prefix = `${subdir.replace(/\/+$/, '')}/`;
-    const entries = [];
-    for (const node of tree) {
-        if (node.type !== 'blob') {
+export const selectTemplateFiles = (entries, subdir) => {
+    const prefix = `${subdir.replace(/^\/+|\/+$/g, '')}/`;
+    const files = [];
+    for (const entry of entries) {
+        // codeload wraps everything in a single top-level dir ("<repo>-<ref>/");
+        // strip that first segment to get the repo-relative path.
+        const slash = entry.name.indexOf('/');
+        if (slash === -1) {
+            continue;
+        }
+        const repoPath = entry.name.slice(slash + 1);
+        if (!repoPath.startsWith(prefix)) {
             continue;
         }
-        if (!node.path.startsWith(prefix)) {
+        const path = repoPath.slice(prefix.length);
+        if (path === '') {
             continue;
         }
-        const path = node.path.slice(prefix.length);
-        if (node.mode === '120000') {
-            entries.push({ kind: 'symlink', path, repoPath: node.path });
+        if (entry.type === '2') {
+            files.push({ kind: 'symlink', path, target: entry.linkname });
         }
-        else {
-            entries.push({
+        else if (entry.type === '0' || entry.type === '7') {
+            files.push({
                 kind: 'file',
                 path,
-                repoPath: node.path,
-                executable: node.mode === '100755',
+                bytes: entry.data,
+                executable: (entry.mode & 0o111) !== 0,
             });
         }
+        // Directories ('5') and any other node types are intentionally skipped.
     }
-    return entries;
+    return files;
 };
-/**
- * Resolve a template to the exact set of files to write. Pins everything to a
- * single immutable commit: the ref is resolved to a commit sha, the tree is
- * read from that commit's tree, and every blob is later fetched by that same
- * commit — so a push to the template repo mid-copy can't produce a mismatched
- * checkout.
- */
-export const resolveTemplate = async (template) => {
-    const { owner, repo, ref, subdir } = template.source;
-    const api = githubApiBase();
-    const commit = parseCommit(await getJson(`${api}/repos/${owner}/${repo}/commits/${ref}`));
-    const { truncated, tree } = parseTree(await getJson(`${api}/repos/${owner}/${repo}/git/trees/${commit.treeSha}?recursive=1`));
-    if (truncated) {
-        throw new Error(`GitHub returned a truncated file tree for ${owner}/${repo}; cannot reliably copy template "${template.id}".`);
-    }
-    const entries = selectSubtreeEntries(tree, subdir);
-    if (entries.length === 0) {
-        throw new Error(`Template subdirectory "${subdir}" was not found in ${owner}/${repo}@${ref}.`);
+const tarballUrl = (template) => {
+    const { owner, repo, ref } = template.source;
+    return `${codeloadBase()}/${owner}/${repo}/tar.gz/${ref}`;
+};
+const friendlyGithubError = (err, url) => {
+    if (isAxiosError(err)) {
+        const status = err.response?.status;
+        if (status === 404) {
+            return new Error(`GitHub returned 404 for ${url}. The template repo or ref may have moved.`);
+        }
+        if (status === 403 || status === 429) {
+            return new Error(`GitHub rate limited the template download (${url}). Set a GITHUB_TOKEN environment variable to raise the limit, then retry.`);
+        }
     }
-    log.debug('bootstrap: resolved %d files for template "%s" at %s', entries.length, template.id, commit.commitSha);
-    return { commitSha: commit.commitSha, entries };
+    return err instanceof Error ? err : new Error(String(err));
 };
-const rawUrl = (template, commitSha, repoPath) => `${githubRawBase()}/${template.source.owner}/${template.source.repo}/${commitSha}/${repoPath}`;
-/** Download a file's raw bytes, pinned to the resolved commit. */
-export const fetchFileBytes = async (template, commitSha, repoPath) => {
-    const url = rawUrl(template, commitSha, repoPath);
+/**
+ * Download a template and resolve it to the exact set of files to write. The
+ * entire subtree is captured in one tarball request, so the copy is atomically
+ * consistent: a push to the template repo mid-download cannot produce a
+ * mismatched checkout (unlike fetching a file list and then each blob).
+ */
+export const downloadTemplate = async (template) => {
+    const url = tarballUrl(template);
+    let gzipped;
     try {
         const res = await axios.get(url, {
             responseType: 'arraybuffer',
-            headers: rawHeaders(),
+            headers: downloadHeaders(),
+            timeout: 30000,
         });
-        return Buffer.from(res.data);
+        gzipped = Buffer.from(res.data);
     }
     catch (err) {
         throw friendlyGithubError(err, url);
     }
-};
-/**
- * Read a symlink's target. In a git blob a symlink is stored as a regular file
- * whose contents are the (relative) link target, so the raw bytes are exactly
- * the string we pass to `symlink(2)`.
- */
-export const fetchSymlinkTarget = async (template, commitSha, repoPath) => {
-    const bytes = await fetchFileBytes(template, commitSha, repoPath);
-    return bytes.toString('utf8');
+    let tar;
+    try {
+        tar = Buffer.from(gunzipSync(new Uint8Array(gzipped)));
+    }
+    catch (err) {
+        throw new Error(`Failed to decompress the template archive from ${url}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const { owner, repo, ref, subdir } = template.source;
+    const files = selectTemplateFiles(parseTar(tar), subdir);
+    if (files.length === 0) {
+        throw new Error(`Template subdirectory "${subdir}" was not found in ${owner}/${repo}@${ref}.`);
+    }
+    log.debug('bootstrap: resolved %d files for template "%s" from %s', files.length, template.id, url);
+    return files;
 };

package/utils/branch_notice.js

@@ -0,0 +1,22 @@
+import chalk from 'chalk';
+import { log } from '../log.js';
+/**
+ * Print a one-line "this command is targeting <branch>" notice to **stderr** so
+ * the user can sanity-check they're acting on the branch they think they are —
+ * before a `status` / `plan` / `apply` / `env pull` does its work. This is the
+ * cheap guardrail that catches "I planned against the wrong branch" / "I pulled
+ * env from the wrong branch" before it bites.
+ *
+ * - Skipped for machine-readable output (`--output json|yaml`) so it never has
+ *   to be reasoned about by a script; it's stderr-only regardless, keeping
+ *   `--output table` stdout clean for piping too.
+ * - `verb` is the leading phrase, e.g. `'Planning against branch'` →
+ *   `→ Planning against branch main (br-…)`.
+ */
+export const announceTargetBranch = (props, branch, verb) => {
+    if (props.output === 'json' || props.output === 'yaml') {
+        return;
+    }
+    const suffix = branch.usedDefault ? chalk.dim(' · project default') : '';
+    log.info('%s %s %s %s%s', chalk.dim('→'), verb, chalk.cyan.bold(branch.branchName), chalk.dim(`(${branch.branchId})`), suffix);
+};

package/utils/enrichers.js

@@ -40,6 +40,45 @@ export const branchIdFromProps = async (props) => {
     props.branchId = await getBranchIdFromProps(props);
     return props.branchId;
 };
+export const resolveBranchRef = async (props) => {
+    const branch = 'branch' in props && typeof props.branch === 'string'
+        ? props.branch
+        : props.id;
+    const { data } = await props.apiClient.listProjectBranches({
+        projectId: props.projectId,
+    });
+    const branches = data.branches;
+    if (branch) {
+        const ref = branch.toString();
+        const found = looksLikeBranchId(ref)
+            ? branches.find((b) => b.id === ref)
+            : branches.find((b) => b.name === ref);
+        if (found) {
+            return {
+                branchId: found.id,
+                branchName: found.name ?? found.id,
+                usedDefault: false,
+            };
+        }
+        // A `br-…` id absent from the listing is still usable as an id (trust it like
+        // branchIdResolve does); only an unresolved *name* is a genuine error.
+        if (looksLikeBranchId(ref)) {
+            return { branchId: ref, branchName: ref, usedDefault: false };
+        }
+        throw new Error(`Branch ${ref} not found.\nAvailable branches: ${branches
+            .map((b) => b.name)
+            .join(', ')}`);
+    }
+    const defaultBranch = branches.find((b) => b.default);
+    if (!defaultBranch) {
+        throw new Error('No default branch found');
+    }
+    return {
+        branchId: defaultBranch.id,
+        branchName: defaultBranch.name ?? defaultBranch.id,
+        usedDefault: true,
+    };
+};
 export const resolveSingleDatabase = async (props) => {
     const { data } = await props.apiClient.listProjectBranchDatabases(props.projectId, props.branchId);
     const databases = data.databases;