neonctl 2.26.1 → 2.26.2

package/commands/auth.js

@@ -110,6 +110,9 @@ export const ensureAuth = async (props) => {
     // login. It uses an API key / stored credentials when present (harmless),
     // otherwise it proceeds with no API client.
     const isBootstrap = props._[0] === 'bootstrap';
+    // `init` manages its own auth flow (asks the user if they have an account,
+    // then triggers OAuth at the right time). Skip the global auth middleware.
+    const isInit = props._[0] === 'init';
     // Use existing API key or handle auth command
     if (props.apiKey || props._[0] === 'auth') {
         if (props.apiKey) {
@@ -162,6 +165,10 @@ export const ensureAuth = async (props) => {
         log.debug('bootstrap: no usable credentials; continuing without auth');
         return;
     }
+    if (isInit) {
+        log.debug('init: skipping global auth; init manages its own auth flow');
+        return;
+    }
     // Start new auth flow if no valid token exists or refresh failed
     const apiKey = await authFlow(props);
     props.apiKey = apiKey;

package/commands/bootstrap.js

@@ -6,7 +6,7 @@ import prompts from 'prompts';
 import which from 'which';
 import { isCi } from '../env.js';
 import { log } from '../log.js';
-import { FALLBACK_TEMPLATES, fetchFileBytes, fetchSymlinkTarget, fetchTemplates, findTemplate, resolveTemplate, templateIds, } from '../utils/bootstrap.js';
+import { FALLBACK_TEMPLATES, downloadTemplate, fetchTemplates, findTemplate, templateIds, } from '../utils/bootstrap.js';
 // The directory positional is optional: omitting it in an interactive terminal
 // prompts for one. In a non-interactive context a missing directory is an error.
 export const command = 'bootstrap [directory]';
@@ -101,18 +101,18 @@ const resolveTemplateList = async (props) => props.template && findTemplate(FALL
     ? FALLBACK_TEMPLATES
     : fetchTemplates();
 /**
- * The picker label for a template: the title prefixed with the Neon services it
- * uses as a dim badge, e.g. "[Postgres · Functions] Hono API …". The badge is
- * styled with chalk.dim only (never a foreground color) so it survives the
- * cyan/underline `prompts` paints over the focused row — dim resets with the
- * intensity SGR, leaving the row's color and underline intact. The one-line
- * description renders under the title on focus (handled by `prompts`).
+ * The picker label for a template: the title first, then the Neon services it
+ * uses as a dim, italic suffix, e.g. "Hono API …  Postgres · Functions". The
+ * suffix is styled with chalk.dim (and italic) only — never a foreground color —
+ * so it survives the cyan/underline `prompts` paints over the focused row: dim
+ * and italic reset with their own SGRs, leaving the row's color and underline
+ * intact. Descriptions are intentionally omitted to keep the picker uncluttered.
  */
 const formatTemplateTitle = (template) => {
     if (!template.services || template.services.length === 0) {
         return template.title;
     }
-    return `${chalk.dim(`[${template.services.join(' · ')}]`)} ${template.title}`;
+    return `${template.title}  ${chalk.dim.italic(template.services.join(' · '))}`;
 };
 const resolveSelectedTemplate = async (props, interactive, templates) => {
     if (props.template) {
@@ -141,7 +141,6 @@ const resolveSelectedTemplate = async (props, interactive, templates) => {
         message: 'Which template would you like to use?',
         choices: templates.map((template) => ({
             title: formatTemplateTitle(template),
-            description: template.description,
             value: template.id,
         })),
         initial: 0,
@@ -207,25 +206,23 @@ const ensureTargetUsable = (dir, force) => {
 };
 const scaffold = async (template, targetDir) => {
     log.info('Fetching template "%s" from GitHub…', template.id);
-    const { commitSha, entries } = await resolveTemplate(template);
+    const files = await downloadTemplate(template);
     mkdirSync(targetDir, { recursive: true });
-    log.info('Scaffolding %d files into %s…', entries.length, targetDir);
-    await mapWithConcurrency(entries, 8, async (entry) => {
-        const dest = join(targetDir, entry.path);
+    log.info('Scaffolding %d files into %s…', files.length, targetDir);
+    for (const file of files) {
+        const dest = join(targetDir, file.path);
         mkdirSync(dirname(dest), { recursive: true });
-        if (entry.kind === 'symlink') {
-            const target = await fetchSymlinkTarget(template, commitSha, entry.repoPath);
-            writeSymlink(dest, target);
+        if (file.kind === 'symlink') {
+            writeSymlink(dest, file.target);
         }
         else {
-            const bytes = await fetchFileBytes(template, commitSha, entry.repoPath);
-            writeFileSync(dest, bytes);
-            if (entry.executable) {
+            writeFileSync(dest, file.bytes);
+            if (file.executable) {
                 chmodSync(dest, 0o755);
             }
         }
-    });
-    return entries.length;
+    }
+    return files.length;
 };
 const writeSymlink = (dest, target) => {
     if (isSymlink(dest)) {
@@ -561,16 +558,6 @@ const displayDir = (targetDir) => {
     }
     return rel.startsWith('..') ? targetDir : rel;
 };
-const mapWithConcurrency = async (items, limit, fn) => {
-    const queue = [...items];
-    const worker = async () => {
-        for (let next = queue.shift(); next !== undefined; next = queue.shift()) {
-            await fn(next);
-        }
-    };
-    const workers = Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, () => worker());
-    await Promise.all(workers);
-};
 const isSymlink = (path) => {
     try {
         return lstatSync(path).isSymbolicLink();

package/commands/checkout.js

@@ -1,6 +1,7 @@
 import { isAxiosError } from 'axios';
+import chalk from 'chalk';
 import prompts from 'prompts';
-import { applyContext, readContextFile } from '../context.js';
+import { applyContext, contextBranch, readContextFile } from '../context.js';
 import { isCi } from '../env.js';
 import { log } from '../log.js';
 import { createBranch, pickBranchInteractively, } from '../utils/branch_picker.js';
@@ -47,6 +48,13 @@ export const builder = (argv) => argv
     ],
 ]);
 export const handler = async (props) => {
+    // Show where the context is pinned *before* we switch it, so the user sees the move
+    // ("currently on X" → "checked out Y") and can catch a checkout they didn't mean to make.
+    // Read straight from `.neon` (a name, no API call); silent when nothing is pinned yet.
+    const previousBranch = contextBranch(readContextFile(props.contextFile));
+    if (previousBranch) {
+        log.info('%s Currently on branch %s', chalk.dim('→'), chalk.cyan.bold(previousBranch));
+    }
     // Branch listing is project-scoped, so `projectId` is the only thing
     // `checkout` actually needs. Resolve it through the standard chain
     // (--project-id flag > .neon file > single-project auto-detect); when

package/commands/config.js

@@ -3,7 +3,8 @@ import { apply, createBranch as createBranchFromPolicy, inspect, loadConfigFromF
 import { toNeonConfigView } from '../config_format.js';
 import { log } from '../log.js';
 import { loadEnvFileIntoProcess } from '../env_file.js';
-import { branchIdFromProps, fillSingleProject } from '../utils/enrichers.js';
+import { fillSingleProject, resolveBranchRef } from '../utils/enrichers.js';
+import { announceTargetBranch } from '../utils/branch_notice.js';
 import { bundleEntry } from '../utils/esbuild.js';
 import { zipBundle } from '../utils/zip.js';
 import { writer } from '../writer.js';
@@ -119,7 +120,13 @@ const loadConfig = async (props) => {
     return config;
 };
 export const status = async (props) => {
-    const branchId = await branchIdFromProps(props);
+    const branch = await resolveBranchRef(props);
+    // `--config-json` is a script-friendly mode that emits only JSON to stdout, so keep it
+    // pristine; the regular human view gets the "which branch am I inspecting" guardrail.
+    if (!props.configJson) {
+        announceTargetBranch(props, branch, 'Inspecting branch');
+    }
+    const branchId = branch.branchId;
     const live = await inspect({
         projectId: props.projectId,
         branchId,
@@ -152,7 +159,9 @@ export const status = async (props) => {
 };
 export const planCmd = async (props) => {
     const config = await loadConfig(props);
-    const branchId = await branchIdFromProps(props);
+    const branch = await resolveBranchRef(props);
+    announceTargetBranch(props, branch, 'Planning against branch');
+    const branchId = branch.branchId;
     // `plan` is a dry run that never bundles, so its options don't accept (or need)
     // an injected bundler — only `apply` does (it uses neonctlBundler).
     const result = await plan(config, {
@@ -166,7 +175,9 @@ export const planCmd = async (props) => {
 };
 export const applyCmd = async (props) => {
     const config = await loadConfig(props);
-    const branchId = await branchIdFromProps(props);
+    const branch = await resolveBranchRef(props);
+    announceTargetBranch(props, branch, 'Applying to branch');
+    const branchId = branch.branchId;
     const result = await apply(config, {
         projectId: props.projectId,
         branchId,

package/commands/dev.js

@@ -480,9 +480,8 @@ const spawnChild = (unit, runtimePath, bundlePath) => {
 const writeBundle = async (source, bundleDir) => {
     const files = await bundleEntry(source);
     mkdirSync(bundleDir, { recursive: true });
-    // bundleEntry emits `index.mjs` (+ `index.mjs.map`). The `.mjs` extension makes Node load
-    // it as ESM directly, so no `package.json` `"type": "module"` marker is needed, and esbuild
-    // points the sourcemap link at `index.mjs.map` for us.
+    // bundleEntry emits a single `index.mjs` (no source map). The `.mjs` extension makes Node
+    // load it as ESM directly, so no `package.json` `"type": "module"` marker is needed.
     for (const [name, contents] of Object.entries(files)) {
         writeFileSync(join(bundleDir, name), contents);
     }

package/commands/env.js

@@ -4,7 +4,8 @@ import { existsSync } from 'node:fs';
 import { log } from '../log.js';
 import { resolveNeonEnvVars } from '../dev/env.js';
 import { mergeEnvFile, readEnvFile, resolveEnvFilePath } from '../env_file.js';
-import { branchIdFromProps, fillSingleProject } from '../utils/enrichers.js';
+import { fillSingleProject, resolveBranchRef } from '../utils/enrichers.js';
+import { announceTargetBranch } from '../utils/branch_notice.js';
 export const command = 'env';
 export const describe = "Manage a branch's Neon env variables locally";
 /**
@@ -33,15 +34,23 @@ export const builder = (argv) => argv
 })
     .example('$0 env pull', "Write the linked branch's Neon vars into .env.local (or .env if present)")
     .example('$0 env pull --branch preview --file .env.preview', 'Pull a specific branch into a specific file'), async (args) => {
-    await pull(args);
+    // Explicit `env pull` announces the branch it's reading from up front so the user
+    // can catch "pulled env from the wrong branch" before it overwrites their .env. The
+    // bundled auto-pull (link / checkout / apply) stays quiet — those already report the
+    // branch they pinned/applied to.
+    await pull(args, { announce: true });
 })
     .demandCommand(1);
 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));
-export const pull = async (props) => {
+export const pull = async (props, opts = {}) => {
     const cwd = props.cwd ?? process.cwd();
-    const branchId = await branchIdFromProps(props);
+    const branch = await resolveBranchRef(props);
+    if (opts.announce) {
+        announceTargetBranch(props, branch, 'Pulling env from branch');
+    }
+    const branchId = branch.branchId;
     // Resolve the target file first and layer its current contents under the resolver's env
     // source. This lets `fetchEnv` reuse one-time secrets that are already on disk — Neon Auth
     // keys and the unified branch credential's `api_token` / `s3_secret_access_key`, which the

package/commands/init.js

@@ -1,4 +1,4 @@
-import { interactiveInit, orchestrate } from 'neon-init';
+import { detectAgent, enrichResponse, interactiveInit, orchestrate, routeDataStep, } from 'neon-init';
 import { sendError } from '../analytics.js';
 import { log } from '../log.js';
 export const command = 'init';
@@ -11,6 +11,10 @@ export const builder = (yargs) => yargs
     alias: 'a',
     type: 'string',
     describe: 'Agent to configure (cursor, copilot, claude, etc.).',
+})
+    .option('data', {
+    type: 'string',
+    describe: 'JSON object with a "step" field to route to a specific phase and phase-specific options.',
 })
     .option('skip-neon-auth', {
     type: 'boolean',
@@ -30,14 +34,36 @@ export const builder = (yargs) => yargs
     .strict(false);
 export const handler = async (argv) => {
     try {
-        if (argv.agent !== undefined) {
+        // Auto-detect agent from environment if --agent not explicitly provided.
+        // For IDE-based detection (Cursor, VS Code, Windsurf), require non-TTY stdin
+        // to distinguish "agent spawned this" from "human typed this in terminal".
+        const agent = argv.agent || (!process.stdin.isTTY ? detectAgent() : null) || undefined;
+        const isAgentMode = agent !== undefined;
+        // --data with a "step" field routes to the appropriate phase
+        if (argv.data && isAgentMode) {
+            let data;
+            try {
+                data = JSON.parse(argv.data);
+            }
+            catch {
+                log.error('Invalid JSON in --data flag. Expected a JSON object.');
+                process.exit(1);
+                return;
+            }
+            if (typeof data.step === 'string') {
+                const result = await routeDataStep(data, agent);
+                log.info(JSON.stringify(enrichResponse(result), null, 2));
+                return;
+            }
+        }
+        if (isAgentMode) {
             const result = await orchestrate({
-                agent: argv.agent || undefined,
+                agent,
                 skipNeonAuth: argv.skipNeonAuth,
                 skipMigrations: argv.skipMigrations,
                 preview: argv.preview,
             });
-            log.info(JSON.stringify(result, null, 2));
+            log.info(JSON.stringify(enrichResponse(result), null, 2));
         }
         else {
             await interactiveInit({ preview: argv.preview });

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.2",
   "description": "CLI tool for NeonDB Cloud management",
   "main": "index.js",
   "author": "NeonDB",
@@ -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/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;

package/utils/esbuild.js

@@ -59,7 +59,6 @@ const bundleViaModule = async (source, loadEsbuild) => {
         // output as a module without needing a `package.json` type marker alongside it.
         outfile: 'index.mjs',
         write: false,
-        sourcemap: true,
         minify: true,
         format: 'esm',
         platform: 'node',
@@ -73,8 +72,8 @@ const bundleViaModule = async (source, loadEsbuild) => {
         throw new Error(`Failed to bundle function from ${source}. ${message(err)}`.trim());
     });
     const files = result.outputFiles ?? [];
-    // write:false with one entry always yields index.mjs + index.mjs.map; an empty set
-    // means the API contract changed under us — fail loud rather than ship an
+    // write:false with one entry always yields index.mjs (no source map — we don't emit one);
+    // an empty set means the API contract changed under us — fail loud rather than ship an
     // empty archive.
     if (files.length === 0) {
         throw new Error(`Failed to bundle function from ${source}. esbuild produced no output.`);
@@ -123,7 +122,6 @@ const bundleViaBinary = async (source) => {
             source,
             '--bundle',
             `--outfile=${outfile}`,
-            '--sourcemap',
             '--minify',
             '--format=esm',
             '--platform=node',
@@ -133,9 +131,10 @@ const bundleViaBinary = async (source) => {
         if (code !== 0) {
             throw new Error(`Failed to bundle function from ${source}. ${stderr.trim()}`.trim());
         }
+        // No `--sourcemap`: the Functions runtime has no source-map support, so an uploaded
+        // `index.mjs.map` is never consumed — emitting it only inflated the archive.
         return {
             'index.mjs': new Uint8Array(readFileSync(outfile)),
-            'index.mjs.map': new Uint8Array(readFileSync(`${outfile}.map`)),
         };
     }
     finally {

package/utils/zip.js

@@ -1,4 +1,4 @@
 import { zipSync } from 'fflate';
-// Zip the esbuild output (index.mjs + index.mjs.map) into the archive the Functions
-// deploy endpoint expects. Compression level 6 matches the previous bundler.
+// Zip the esbuild output (index.mjs) into the archive the Functions deploy endpoint
+// expects. Compression level 6 matches the previous bundler.
 export const zipBundle = (entries) => zipSync(entries, { level: 6 });