neonctl 2.24.0 → 2.24.2

package/commands/checkout.js

@@ -1,13 +1,13 @@
-import { EndpointType } from '@neondatabase/api-client';
 import { isAxiosError } from 'axios';
 import prompts from 'prompts';
-import { retryOnLock } from '../api.js';
 import { applyContext, readContextFile } from '../context.js';
 import { isCi } from '../env.js';
 import { log } from '../log.js';
+import { createBranch, pickBranchInteractively, } from '../utils/branch_picker.js';
 import { fillSingleProject } from '../utils/enrichers.js';
 import { looksLikeBranchId } from '../utils/formats.js';
-import { applyPolicyOnCreate } from './config.js';
+import { autoPullEnvAfterPin } from './env.js';
+import { applyPolicyOnCreate, createBranchFromPolicyOnCheckout, } from './config.js';
 import { handler as linkHandler } from './link.js';
 // The positional is optional: omitting it in an interactive terminal opens a
 // branch picker. In non-interactive contexts a missing branch is an error.
@@ -24,6 +24,13 @@ export const builder = (argv) => argv
         describe: 'Project ID',
         type: 'string',
     },
+    'env-pull': {
+        describe: "Pull the branch's Neon env vars (DATABASE_URL, …) into a local .env after " +
+            'checkout. On by default; use --no-env-pull to skip (e.g. when injecting env at ' +
+            'runtime with `neon-env run` / `neon dev`).',
+        type: 'boolean',
+        default: true,
+    },
 })
     .example([
     [
@@ -45,7 +52,7 @@ export const handler = async (props) => {
     // (--project-id flag > .neon file > single-project auto-detect); when
     // nothing resolves, fall back to an interactive `neonctl link`.
     const projectId = await resolveProjectId(props);
-    const { branchId, created } = await resolveBranchId(props, projectId);
+    const { branchId, created, policyApplied } = await resolveBranchId(props, projectId);
     const orgId = await resolveOrgId(props, projectId);
     // `checkout` is a thin helper over `set-context`. It fully "heals" the
     // context file: it always (re)writes `projectId`, `branchId`, and `orgId`
@@ -57,44 +64,59 @@ export const handler = async (props) => {
         branchId,
     });
     log.info('Checked out branch %s on project %s%s. Updated %s.', branchId, projectId, orgId ? ` (org ${orgId})` : '', props.contextFile);
-    // Only when checkout just *created* the branch do we apply the local neon.ts policy,
-    // so a new branch comes up with the declared settings/infra immediately. Checking out an
-    // existing branch never reconciles it — that's an explicit `neonctl deploy` / `config
-    // apply`. No neon.ts on disk → nothing to apply.
-    if (created) {
+    // When checkout *created* the branch and a neon.ts exists, the branch was created straight
+    // from the policy (evaluated as a new branch) so its settings/infra are already applied —
+    // see `policyApplied`. The fallback below covers the case where the branch was created bare
+    // (e.g. a policy-driven create wasn't possible); `applyPolicyOnCreate` is a no-op when there
+    // is no neon.ts on disk. Checking out an existing branch never reconciles it.
+    if (created && !policyApplied) {
         await applyPolicyOnCreate({
             projectId,
             branchId,
             ...(props.apiKey ? { apiKey: props.apiKey } : {}),
+            ...(props.apiHost ? { apiHost: props.apiHost } : {}),
         });
     }
+    // Bundle `env pull` so the branch-first loop is just link + checkout: the branch you
+    // checked out is immediately usable for local dev. `--no-env-pull` opts out.
+    await autoPullEnvAfterPin({
+        ...props,
+        projectId,
+        branch: branchId,
+        envPull: props.envPull,
+    });
 };
 const resolveBranchId = async (props, projectId) => {
     const branches = (await props.apiClient.listProjectBranches({ projectId }))
         .data.branches;
     if (!props.id) {
-        const picked = await pickBranchInteractively(branches);
+        const picked = await pickBranchInteractively(branches, {
+            message: 'Which branch would you like to check out?',
+            nonInteractiveMessage: 'No branch specified. Pass a branch name or id (e.g. `neonctl checkout main`), ' +
+                'or run interactively to pick one from a list.',
+        });
         if (picked.kind === 'existing') {
-            return { branchId: picked.branchId, created: false };
+            return {
+                branchId: picked.branchId,
+                created: false,
+                policyApplied: false,
+            };
         }
         // The user chose "create a new branch" from the picker.
-        return {
-            branchId: await createBranch(props, projectId, picked.name, branches),
-            created: true,
-        };
+        return createCheckoutBranch(props, projectId, picked.name, branches);
     }
     const ref = props.id;
     // A `br-…` value is an id; match strictly by id and never offer to create.
     if (looksLikeBranchId(ref)) {
         const byId = branches.find((b) => b.id === ref);
         if (byId) {
-            return { branchId: byId.id, created: false };
+            return { branchId: byId.id, created: false, policyApplied: false };
         }
         throw new Error(notFoundMessage(ref, branches));
     }
     const byName = branches.find((b) => b.name === ref);
     if (byName) {
-        return { branchId: byName.id, created: false };
+        return { branchId: byName.id, created: false, policyApplied: false };
     }
     // Name not found: offer to create it interactively, mirroring `branch create`.
     if (isCi() || !process.stdout.isTTY) {
@@ -110,90 +132,38 @@ const resolveBranchId = async (props, projectId) => {
     if (!create) {
         throw new Error(`Aborted: branch "${ref}" was not found and not created.`);
     }
+    return createCheckoutBranch(props, projectId, ref, branches);
+};
+/**
+ * Create the branch to check out. When a `neon.ts` exists, route through the policy-driven
+ * create so the new branch comes up branched from the policy's `parent` and configured with
+ * its declared TTL / compute / services (evaluated as a *new* branch). Otherwise fall back to
+ * a bare branch off the default — the handler then applies the policy (a no-op with no
+ * `neon.ts`).
+ */
+const createCheckoutBranch = async (props, projectId, name, branches) => {
+    const fromPolicy = await createBranchFromPolicyOnCheckout({
+        projectId,
+        branchName: name,
+        ...(props.apiKey ? { apiKey: props.apiKey } : {}),
+        ...(props.apiHost ? { apiHost: props.apiHost } : {}),
+    });
+    if (fromPolicy) {
+        return {
+            branchId: fromPolicy.branchId,
+            created: true,
+            policyApplied: true,
+        };
+    }
     return {
-        branchId: await createBranch(props, projectId, ref, branches),
+        branchId: await createBranch(props.apiClient, projectId, name, branches),
         created: true,
+        policyApplied: false,
     };
 };
 const notFoundMessage = (ref, branches) => `Branch ${ref} not found.\nAvailable branches: ${branches
     .map((b) => b.name)
     .join(', ')}`;
-/** Sentinel `value` for the "create a new branch" choice (no branch id can collide). */
-const CREATE_BRANCH_CHOICE = Symbol('create-branch');
-const pickBranchInteractively = async (branches) => {
-    if (isCi() || !process.stdout.isTTY) {
-        throw new Error('No branch specified. Pass a branch name or id (e.g. `neonctl checkout main`), ' +
-            'or run interactively to pick one from a list.');
-    }
-    // The default selection is the project's default branch when there are branches to
-    // show; the create option sits at the top, so offset the default index by one.
-    const defaultBranchIndex = branches.findIndex((b) => b.default);
-    const initial = defaultBranchIndex >= 0 ? defaultBranchIndex + 1 : 0;
-    const { choice } = await prompts({
-        type: 'select',
-        name: 'choice',
-        message: 'Which branch would you like to check out?',
-        choices: [
-            { title: '＋ Create a new branch…', value: CREATE_BRANCH_CHOICE },
-            ...branches.map((b) => ({
-                title: `${b.default ? '✱ ' : ''}${b.name} (${b.id})`,
-                value: b.id,
-            })),
-        ],
-        initial,
-    });
-    if (choice === undefined) {
-        throw new Error('Aborted: no branch selected.');
-    }
-    if (choice === CREATE_BRANCH_CHOICE) {
-        return { kind: 'create', name: await promptNewBranchName(branches) };
-    }
-    return { kind: 'existing', branchId: choice };
-};
-/**
- * Prompt for a new branch name, rejecting empty input and names already taken on the
- * project (so we never silently check out a different, pre-existing branch).
- */
-const promptNewBranchName = async (branches) => {
-    const existing = new Set(branches.map((b) => b.name));
-    const { name } = await prompts({
-        type: 'text',
-        name: 'name',
-        message: 'New branch name:',
-        validate: (value) => {
-            const trimmed = value.trim();
-            if (trimmed === '')
-                return 'Branch name cannot be empty.';
-            if (existing.has(trimmed))
-                return `A branch named "${trimmed}" already exists.`;
-            return true;
-        },
-    });
-    const trimmed = typeof name === 'string' ? name.trim() : '';
-    if (trimmed === '') {
-        throw new Error('Aborted: no branch name provided.');
-    }
-    return trimmed;
-};
-/**
- * Create a branch with the same defaults as `neonctl branch create --name <name>`:
- * branched from the project's default branch with a read-write compute endpoint.
- */
-const createBranch = async (props, projectId, name, branches) => {
-    const defaultBranch = branches.find((b) => b.default);
-    if (!defaultBranch) {
-        throw new Error('No default branch found');
-    }
-    const { data } = await retryOnLock(() => props.apiClient.createProjectBranch(projectId, {
-        branch: { name, parent_id: defaultBranch.id },
-        endpoints: [{ type: EndpointType.ReadWrite }],
-    }));
-    if (defaultBranch.protected) {
-        log.warning('The parent branch is protected; a unique role password has been generated for the new branch.');
-    }
-    log.info('Created branch %s (%s).', data.branch.name, data.branch.id);
-    return data.branch.id;
-};
 /**
  * Resolve the org id to heal into the context file.
  *

package/commands/config.js

@@ -1,5 +1,5 @@
 import { resolveConfig } from '@neondatabase/config';
-import { apply, inspect, loadConfigFromFile, plan, } from '@neondatabase/config-runtime';
+import { apply, createBranch as createBranchFromPolicy, inspect, loadConfigFromFile, plan, } from '@neondatabase/config-runtime';
 import { toNeonConfigView } from '../config_format.js';
 import { log } from '../log.js';
 import { loadEnvFileIntoProcess } from '../env_file.js';
@@ -107,6 +107,7 @@ export const status = async (props) => {
         projectId: props.projectId,
         branchId,
         ...(props.apiKey ? { apiKey: props.apiKey } : {}),
+        ...(props.apiHost ? { apiHost: props.apiHost } : {}),
         ...(props.runtimeApi ? { api: props.runtimeApi } : {}),
     });
     // The pulled `config` carries the branch's tuning inside a closure that JSON can't
@@ -141,6 +142,7 @@ export const planCmd = async (props) => {
         projectId: props.projectId,
         branchId,
         ...(props.apiKey ? { apiKey: props.apiKey } : {}),
+        ...(props.apiHost ? { apiHost: props.apiHost } : {}),
         ...(props.runtimeApi ? { api: props.runtimeApi } : {}),
     });
     reportPushResult(props, result, 'plan');
@@ -152,6 +154,7 @@ export const applyCmd = async (props) => {
         projectId: props.projectId,
         branchId,
         ...(props.apiKey ? { apiKey: props.apiKey } : {}),
+        ...(props.apiHost ? { apiHost: props.apiHost } : {}),
         ...(props.runtimeApi ? { api: props.runtimeApi } : {}),
         ...(props.updateExisting ? { updateExisting: true } : {}),
         ...(props.allowProtected ? { allowProtectedBranch: true } : {}),
@@ -235,11 +238,16 @@ export const applyPolicyOnCreate = async (props) => {
         projectId: props.projectId,
         branchId: props.branchId,
         ...(props.apiKey ? { apiKey: props.apiKey } : {}),
+        ...(props.apiHost ? { apiHost: props.apiHost } : {}),
         ...(props.runtimeApi ? { api: props.runtimeApi } : {}),
         updateExisting: true,
         allowProtectedBranch: true,
         bundleFunction: neonctlBundler,
     });
+    logPolicyResult(result);
+};
+/** Log a one-line summary of what applying a `neon.ts` policy changed (or that nothing did). */
+const logPolicyResult = (result) => {
     const changes = result.applied.filter((c) => c.action !== 'noop');
     if (changes.length === 0) {
         log.info('neon.ts applied — no changes were needed.');
@@ -247,3 +255,40 @@ export const applyPolicyOnCreate = async (props) => {
     }
     log.info('neon.ts applied — %d change%s: %s', changes.length, changes.length === 1 ? '' : 's', changes.map((c) => `${c.action} ${c.identifier}`).join(', '));
 };
+/**
+ * Create a branch **from** the local `neon.ts` policy. Returns `null` when there is no
+ * `neon.ts` on the path from cwd up to the repo root, so `neonctl checkout` can fall back to a
+ * bare branch create.
+ *
+ * Unlike a bare create followed by {@link applyPolicyOnCreate}, this evaluates the policy for
+ * the **new** branch (`exists: false`): the runtime branches from the policy's `parent` and
+ * brings the branch up with its declared TTL / compute settings / services. That's what makes
+ * a policy keyed on `!branch.exists` (the common "only configure new branches" shape) take
+ * effect on the very first `checkout` — a bare create + `apply` always saw `exists: true` and
+ * skipped that block.
+ */
+export const createBranchFromPolicyOnCheckout = async (props) => {
+    let config;
+    try {
+        ({ config } = await loadConfigFromFile({
+            ...(props.cwd ? { cwd: props.cwd } : {}),
+        }));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (/Could not find a Neon config file/i.test(message))
+            return null;
+        throw err;
+    }
+    const { branchId, branchName, result } = await createBranchFromPolicy(config, {
+        projectId: props.projectId,
+        branchName: props.branchName,
+        ...(props.apiKey ? { apiKey: props.apiKey } : {}),
+        ...(props.apiHost ? { apiHost: props.apiHost } : {}),
+        ...(props.runtimeApi ? { api: props.runtimeApi } : {}),
+        bundleFunction: neonctlBundler,
+    });
+    log.info('Created branch %s (%s) from neon.ts policy.', branchName, branchId);
+    logPolicyResult(result);
+    return { branchId };
+};

package/commands/dev.js

@@ -51,11 +51,12 @@ const runSingleSource = async (props) => {
         throw new Error(`Source file not found: ${source}`);
     }
     const branchId = await resolveBranchId(props);
-    const neonEnv = await resolveDevEnv({
+    const { vars: neonEnv, skipped } = await resolveDevEnv({
         cwd: process.cwd(),
         ...(props.projectId ? { projectId: props.projectId } : {}),
         ...(branchId ? { branchId } : {}),
         ...(props.apiKey ? { apiKey: props.apiKey } : {}),
+        ...(props.apiHost ? { apiHost: props.apiHost } : {}),
     });
     const unit = {
         slug: null,
@@ -63,10 +64,13 @@ const runSingleSource = async (props) => {
         bundleDir: join(process.cwd(), 'node_modules', '.neon-dev'),
         childEnv: buildChildEnv(neonEnv, portFromProps(props.port)),
         label: null,
+        envSummary: { neon: Object.keys(neonEnv), fn: [] },
     };
     // No config reload in single-source mode: there's exactly one file to serve, and
     // nothing to add or remove. neon.ts hot-reload is config-mode only.
-    await runSupervisor([unit]);
+    await runSupervisor([unit], {
+        ...(skipped ? { envNote: skipped.reason } : {}),
+    });
 };
 /**
  * Multi-function mode: serve every function declared in neon.ts. Requires a neon.ts
@@ -85,11 +89,12 @@ const runFromConfig = async (props) => {
         throw new Error('neon.ts has no functions to serve. Add at least one under ' +
             '`preview.functions`, or pass --source <path>.');
     }
-    const neonEnv = await resolveDevEnv({
+    const { vars: neonEnv, skipped } = await resolveDevEnv({
         cwd: process.cwd(),
         ...(props.projectId ? { projectId: props.projectId } : {}),
         ...(branchId ? { branchId } : {}),
         ...(props.apiKey ? { apiKey: props.apiKey } : {}),
+        ...(props.apiHost ? { apiHost: props.apiHost } : {}),
     });
     const units = planFunctionsToUnits(functions, neonEnv, DEFAULT_PORT_BASE);
     // Re-derive the units from neon.ts on demand so the config watcher can hot-add/remove
@@ -102,7 +107,10 @@ const runFromConfig = async (props) => {
             return null;
         return planFunctionsToUnits(re.functions, neonEnv, searchBase);
     };
-    await runSupervisor(units, { configPath, replan });
+    await runSupervisor(units, {
+        reload: { configPath, replan },
+        ...(skipped ? { envNote: skipped.reason } : {}),
+    });
 };
 /**
  * Map a list of {@link PlannedFunction}s to {@link ServedUnit}s, coordinating the search
@@ -174,6 +182,7 @@ const plannedToUnit = (fn, branchEnv, searchBase) => {
         bundleDir: join(process.cwd(), 'node_modules', '.neon-dev', fn.slug),
         childEnv,
         label: fn.slug,
+        envSummary: { neon: Object.keys(branchEnv), fn: Object.keys(fn.env) },
         // Signature of the function's *own* neon.ts config (NOT the dynamically-chosen search
         // base) so reconcile can tell a real change from a no-op save. A search-mode function
         // re-planned with a different base must hash identically, or it would be needlessly
@@ -221,7 +230,8 @@ const READY_PATTERN = /neon-dev:ready (\d+)/;
  * stayed the same. A function whose config (env/port/portless/source) changed is restarted
  * in place; siblings are untouched.
  */
-const runSupervisor = async (units, reload) => {
+const runSupervisor = async (units, options = {}) => {
+    const { reload, envNote } = options;
     if (hasPortlessUnit(units)) {
         assertPortlessAvailable();
     }
@@ -310,7 +320,7 @@ const runSupervisor = async (units, reload) => {
         await Promise.all(running.map((r) => stopUnit(r)));
         throw new Error('No function started. See the output above for details.');
     }
-    printBanner(running);
+    printBanner(running, envNote);
     // Config mode only: watch neon.ts and reconcile the live unit set when it changes.
     // Reconciles are serialized: a burst of saves (editor write-then-format) must not run
     // overlapping diffs against the mutating `running` array. A trailing run coalesces the
@@ -448,7 +458,10 @@ const reconcileOnce = async (running, replan, ops) => {
         await Promise.all(added.map((r) => ops.startUnit(r)));
         for (const r of added) {
             if (r.status === 'ready') {
-                logUnit(r.unit, chalk.green('ready') + ` ${urlFor(r.boundPort)}`);
+                const env = formatEnvSummary(r.unit.envSummary);
+                logUnit(r.unit, chalk.green('ready') +
+                    ` ${urlFor(r.boundPort)}` +
+                    (env ? chalk.dim(`  ${env}`) : ''));
             }
         }
     }
@@ -513,15 +526,13 @@ const spawnSyncCheck = (bin) => {
 const writeBundle = async (source, bundleDir) => {
     const files = await bundleEntry(source);
     mkdirSync(bundleDir, { recursive: true });
-    // The bundle is ESM (`format: 'esm'`), but it's written into a `.js` file under the
-    // user's node_modules — where Node, finding no `"type"`, would treat `.js` as CommonJS
-    // and throw `Unexpected token 'export'`. Drop a `package.json` marker so Node runs it as
-    // ESM. (A bare `out.mjs` would also work but breaks the `out.js.map` sourcemap link.)
-    writeFileSync(join(bundleDir, 'package.json'), '{"type":"module"}\n');
+    // 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.
     for (const [name, contents] of Object.entries(files)) {
         writeFileSync(join(bundleDir, name), contents);
     }
-    return join(bundleDir, 'out.js');
+    return join(bundleDir, 'index.mjs');
 };
 const urlFor = (port) => port === null ? chalk.red('not running') : `http://localhost:${port}`;
 const waitForReady = (child) => new Promise((resolveReady) => {
@@ -567,7 +578,7 @@ const pipeChildOutput = (child, label) => {
     forward('stdout');
     forward('stderr');
 };
-const printBanner = (running) => {
+const printBanner = (running, envNote) => {
     log.info('');
     log.info(chalk.green.bold('  Neon Functions dev server'));
     log.info('');
@@ -575,9 +586,34 @@ const printBanner = (running) => {
         const name = r.unit.label ?? 'function';
         const url = urlFor(r.boundPort);
         log.info(`  ${chalk.dim(name.padEnd(20))} ${url}`);
+        const env = formatEnvSummary(r.unit.envSummary);
+        if (env)
+            log.info(`  ${' '.repeat(20)} ${chalk.dim(env)}`);
+    }
+    if (envNote) {
+        log.info('');
+        log.info(`  ${chalk.yellow('!')} ${chalk.dim(`Neon env: ${envNote}`)}`);
     }
     log.info('');
 };
+/**
+ * Render a unit's injected env into one transparent line for the banner, e.g.
+ * `env: DATABASE_URL, DATABASE_URL_UNPOOLED · neon.ts: RESEND_API_KEY`. Var **names** only
+ * (never values — they're secrets). Returns `''` when nothing is injected, so the caller can
+ * skip the line. Exported for unit testing.
+ */
+export const formatEnvSummary = (summary) => {
+    if (!summary)
+        return '';
+    const parts = [];
+    if (summary.neon.length > 0) {
+        parts.push(`env: ${[...summary.neon].sort().join(', ')}`);
+    }
+    if (summary.fn.length > 0) {
+        parts.push(`neon.ts: ${[...summary.fn].sort().join(', ')}`);
+    }
+    return parts.join(' · ');
+};
 const logUnit = (unit, message) => {
     const prefix = unit.label ? chalk.dim(`[${unit.label}] `) : '';
     log.info(`${prefix}${message}`);

package/commands/env.js

@@ -1,3 +1,4 @@
+import chalk from 'chalk';
 import { NEON_ENV_VAR_KEYS } from '@neondatabase/env';
 import { log } from '../log.js';
 import { resolveNeonEnvVars } from '../dev/env.js';
@@ -5,6 +6,13 @@ import { mergeEnvFile, resolveEnvFilePath } from '../env_file.js';
 import { branchIdFromProps, fillSingleProject } from '../utils/enrichers.js';
 export const command = 'env';
 export const describe = "Manage a branch's Neon env variables locally";
+/**
+ * Shown (to stderr) when `link` / `checkout` skip the bundled env pull because the user passed
+ * `--no-env-pull`. Names the two ways to get the branch's vars without an on-disk file written
+ * eagerly: an explicit `neonctl env pull`, or runtime injection via `neon-env run`.
+ */
+export const ENV_PULL_SKIPPED_HINT = 'Skipped env pull (--no-env-pull). Run `neonctl env pull` to write this branch’s env vars ' +
+    '(DATABASE_URL, …) into a local .env, or inject them at runtime with `neon-env run -- <your dev command>`.';
 export const builder = (argv) => argv
     .usage('$0 env <sub-command> [options]')
     .options({
@@ -23,7 +31,9 @@ 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'), (args) => pull(args))
+    .example('$0 env pull --branch preview --file .env.preview', 'Pull a specific branch into a specific file'), async (args) => {
+    await pull(args);
+})
     .demandCommand(1);
 export const handler = (args) => args;
 /** Every OS-level env var name `@neondatabase/env` can emit, used only for reporting. */
@@ -39,17 +49,62 @@ export const pull = async (props) => {
         projectId: props.projectId,
         branchId,
         ...(props.apiKey ? { apiKey: props.apiKey } : {}),
+        ...(props.apiHost ? { apiHost: props.apiHost } : {}),
         ...(props.runtimeApi ? { api: props.runtimeApi } : {}),
     });
     const neonVars = pickNeonVars(vars);
     if (Object.keys(neonVars).length === 0) {
         log.info('No Neon env variables to pull for this branch (no DATABASE_URL or ' +
             'enabled Auth / Data API).');
-        return;
+        return { status: 'empty' };
     }
     const targetPath = resolveEnvFilePath(cwd, props.file);
     const { written } = mergeEnvFile(targetPath, neonVars);
     log.info('Pulled %d Neon variable%s into %s: %s', written.length, written.length === 1 ? '' : 's', targetPath, written.join(', '));
+    return { status: 'written', written, file: targetPath };
+};
+/**
+ * Pull a freshly-pinned branch's Neon env vars into a local `.env`, bundled into `link` and
+ * `checkout` so the branch-first loop is just *link + checkout* — `env pull` runs for you.
+ *
+ * On by default; `--no-env-pull` opts out (e.g. when env is injected at runtime via
+ * `neon-env run` / `neon dev`, or to keep secrets out of the working tree). The pin is the
+ * command's primary effect and has already succeeded by the time this runs, so a pull failure
+ * degrades to a warning rather than failing the command. Returns what happened so
+ * `link --agent` can fold an accurate note into its JSON message.
+ */
+export const autoPullEnvAfterPin = async (props) => {
+    if (!props.envPull) {
+        log.info(chalk.dim(ENV_PULL_SKIPPED_HINT));
+        return { status: 'skipped' };
+    }
+    try {
+        return await pull(props);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        log.warning('Branch pinned, but pulling its Neon env vars failed: %s\n' +
+            'Run `neonctl env pull` once resolved (e.g. `neonctl deploy` if a declared service ' +
+            'is missing), or inject them at runtime with `neon-env run -- <your dev command>`.', message);
+        return { status: 'failed', message };
+    }
+};
+/**
+ * Render the one-line env-pull note appended to `link --agent`'s JSON `message`, so an agent
+ * reading the structured output knows whether its branch env is already on disk.
+ */
+export const renderAgentPullNote = (result) => {
+    switch (result.status) {
+        case 'written':
+            return ` Pulled ${result.written.length} Neon env var${result.written.length === 1 ? '' : 's'} into ${result.file}.`;
+        case 'empty':
+            return ' No Neon env vars to pull for this branch yet.';
+        case 'skipped':
+            return (' Skipped env pull (--no-env-pull); run `neonctl env pull` later, ' +
+                'or inject env at runtime with `neon-env run -- <your dev command>`.');
+        case 'failed':
+            return ` Could not pull env vars (${result.message}); run \`neonctl env pull\` once resolved.`;
+    }
 };
 /**
  * Keep only the recognized Neon variables from the resolved set, so a stray inherited

package/commands/index.js

@@ -21,6 +21,7 @@ import * as dev from './dev.js';
 import * as config from './config.js';
 import * as deploy from './deploy.js';
 import * as env from './env.js';
+import * as bucket from './bucket.js';
 export default [
     auth,
     users,
@@ -45,4 +46,5 @@ export default [
     config,
     deploy,
     env,
+    bucket,
 ];