neonctl 2.23.1 → 2.24.1

package/commands/env.js

@@ -0,0 +1,121 @@
+import chalk from 'chalk';
+import { NEON_ENV_VAR_KEYS } from '@neondatabase/env';
+import { log } from '../log.js';
+import { resolveNeonEnvVars } from '../dev/env.js';
+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({
+    'project-id': { describe: 'Project ID', type: 'string' },
+    branch: { describe: 'Branch ID or name', type: 'string' },
+})
+    .middleware(fillSingleProject)
+    .command('pull', "Write the branch's Neon env variables to a local .env file", (yargs) => yargs
+    .usage('$0 env pull [options]')
+    .options({
+    file: {
+        describe: 'Target .env file to write. Defaults to an existing .env, ' +
+            'otherwise .env.local. Only Neon variables are updated; other ' +
+            'lines are preserved.',
+        type: 'string',
+    },
+})
+    .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);
+})
+    .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) => {
+    const cwd = props.cwd ?? process.cwd();
+    const branchId = await branchIdFromProps(props);
+    // Reuse `neon dev`'s tiered resolver (neon.ts policy -> plan gate -> fetchEnv, else
+    // pullConfig -> fetchEnv). Unlike dev, an unresolved context or failure is surfaced —
+    // `env pull` is an explicit action, so it should error rather than write nothing.
+    const vars = await resolveNeonEnvVars({
+        cwd,
+        projectId: props.projectId,
+        branchId,
+        ...(props.apiKey ? { apiKey: props.apiKey } : {}),
+        ...(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 { 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
+ * value never lands in the user's `.env` file. (Today `resolveNeonEnvVars` only emits Neon
+ * vars, but filtering keeps the contract explicit and future-proof.)
+ */
+const pickNeonVars = (vars) => {
+    const out = {};
+    for (const name of NEON_VAR_NAMES) {
+        const value = vars[name];
+        if (value !== undefined)
+            out[name] = value;
+    }
+    return out;
+};

package/commands/index.js

@@ -17,6 +17,11 @@ import * as init from './init.js';
 import * as dataApi from './data_api.js';
 import * as neonAuth from './neon_auth.js';
 import * as functions from './functions.js';
+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,
@@ -37,4 +42,9 @@ export default [
     init,
     dataApi,
     functions,
+    dev,
+    config,
+    deploy,
+    env,
+    bucket,
 ];

package/commands/link.js

@@ -3,6 +3,8 @@ import prompts from 'prompts';
 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 { autoPullEnvAfterPin, renderAgentPullNote } from './env.js';
 import { REGIONS } from './projects.js';
 const PROJECTS_LIST_LIMIT = 100;
 const CREATE_NEW_SENTINEL = '__create_new__';
@@ -40,6 +42,13 @@ export const builder = (argv) => argv.usage('$0 link [options]').options({
         type: 'boolean',
         default: false,
     },
+    'env-pull': {
+        describe: "Pull the linked branch's Neon env vars (DATABASE_URL, …) into a local .env after " +
+            'linking. 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,
+    },
 });
 export const handler = async (props) => {
     if (props.agent) {
@@ -134,7 +143,7 @@ const runNonInteractive = async (props, inputs) => {
             projectId: inputs.projectId,
             branchId,
         });
-        printHumanSummary(props, {
+        await finalizeHumanLink(props, {
             contextFile: props.contextFile,
             orgId,
             projectId: inputs.projectId,
@@ -153,7 +162,7 @@ const runNonInteractive = async (props, inputs) => {
         projectId: created.project.id,
         branchId: created.branchId,
     });
-    printHumanSummary(props, {
+    await finalizeHumanLink(props, {
         contextFile: props.contextFile,
         orgId,
         projectId: created.project.id,
@@ -187,13 +196,13 @@ const runInteractive = async (props, inputs) => {
         orgId = await promptOrgFromList(orgResolution.orgs);
     }
     if (inputs.projectId) {
-        const branchId = await resolveDefaultBranchId(props, inputs.projectId);
+        const branchId = await resolveInteractiveBranchId(props, inputs.projectId);
         applyContext(props.contextFile, {
             orgId,
             projectId: inputs.projectId,
             branchId,
         });
-        printHumanSummary(props, {
+        await finalizeHumanLink(props, {
             contextFile: props.contextFile,
             orgId,
             projectId: inputs.projectId,
@@ -213,7 +222,7 @@ const runInteractive = async (props, inputs) => {
             projectId: created.project.id,
             branchId: created.branchId,
         });
-        printHumanSummary(props, {
+        await finalizeHumanLink(props, {
             contextFile: props.contextFile,
             orgId,
             projectId: created.project.id,
@@ -228,13 +237,13 @@ const runInteractive = async (props, inputs) => {
     const projects = await listAllProjects(props, orgId);
     const action = await promptProjectChoice(projects, inputs.projectName);
     if (action.type === 'existing') {
-        const branchId = await resolveDefaultBranchId(props, action.projectId);
+        const branchId = await resolveInteractiveBranchId(props, action.projectId);
         applyContext(props.contextFile, {
             orgId,
             projectId: action.projectId,
             branchId,
         });
-        printHumanSummary(props, {
+        await finalizeHumanLink(props, {
             contextFile: props.contextFile,
             orgId,
             projectId: action.projectId,
@@ -257,7 +266,7 @@ const runInteractive = async (props, inputs) => {
         projectId: created.project.id,
         branchId: created.branchId,
     });
-    printHumanSummary(props, {
+    await finalizeHumanLink(props, {
         contextFile: props.contextFile,
         orgId,
         projectId: created.project.id,
@@ -303,19 +312,21 @@ const promptOrgFromList = async (orgs) => {
 };
 const promptProjectChoice = async (projects, suggestedName) => {
     const choices = [
+        { title: '＋ Create new project…', value: CREATE_NEW_SENTINEL },
         ...projects.map((project) => ({
             title: `${project.name} (${project.id})`,
             value: project.id,
         })),
-        { title: '+ Create new project', value: CREATE_NEW_SENTINEL },
     ];
+    // Create sits at the top, so default to the first existing project (index 1) when there
+    // is one; with no projects to show, the create option (index 0) is the only choice.
     const { selection } = await prompts({
         onState: onPromptState,
         type: 'select',
         name: 'selection',
         message: 'Which project would you like to link?',
         choices,
-        initial: choices.length === 1 ? 0 : 0,
+        initial: projects.length > 0 ? 1 : 0,
     });
     if (selection === CREATE_NEW_SENTINEL) {
         return { type: 'create', suggestedName };
@@ -380,12 +391,18 @@ const runAgent = async (props, inputs) => {
     if (projectId) {
         const branchId = await resolveDefaultBranchId(props, projectId);
         applyContext(props.contextFile, { orgId, projectId, branchId });
+        const pullNote = renderAgentPullNote(await autoPullEnvAfterPin({
+            ...props,
+            projectId,
+            branch: branchId,
+            envPull: props.envPull,
+        }));
         emitAgent({
             status: 'linked',
             context_file: props.contextFile,
             context: { orgId, projectId, branchId },
             project: { id: projectId },
-            message: `Linked ${props.contextFile} to project ${projectId} (org ${orgId}) on branch ${branchId}.`,
+            message: `Linked ${props.contextFile} to project ${projectId} (org ${orgId}) on branch ${branchId}.${pullNote}`,
         });
         return;
     }
@@ -414,6 +431,12 @@ const runAgent = async (props, inputs) => {
             projectId: created.project.id,
             branchId: created.branchId,
         });
+        const pullNote = renderAgentPullNote(await autoPullEnvAfterPin({
+            ...props,
+            projectId: created.project.id,
+            branch: created.branchId,
+            envPull: props.envPull,
+        }));
         emitAgent({
             status: 'linked',
             context_file: props.contextFile,
@@ -427,7 +450,7 @@ const runAgent = async (props, inputs) => {
                 name: created.project.name,
                 region_id: created.project.region_id,
             },
-            message: `Created project ${created.project.id} ("${created.project.name ?? projectName}") in ${created.project.region_id ?? regionId} and linked ${props.contextFile}.`,
+            message: `Created project ${created.project.id} ("${created.project.name ?? projectName}") in ${created.project.region_id ?? regionId} and linked ${props.contextFile}.${pullNote}`,
         });
         return;
     }
@@ -589,6 +612,33 @@ const resolveDefaultBranchId = async (props, projectId) => {
     }
     return branch.id;
 };
+/**
+ * Resolve which branch to pin for an interactively-chosen project. When the project has a
+ * single branch there is nothing to choose, so we pin it silently. Otherwise we offer the
+ * shared branch picker (the same "＋ Create a new branch…" + list as `neonctl checkout`),
+ * creating the branch when the user opts to. This makes `link` a full org → project →
+ * branch flow instead of always pinning the default branch.
+ */
+const resolveInteractiveBranchId = async (props, projectId) => {
+    const { data } = await props.apiClient.listProjectBranches({ projectId });
+    const branches = data.branches;
+    if (branches.length <= 1) {
+        const only = branches.find((b) => b.default) ?? branches[0];
+        if (!only) {
+            throw new Error(`Could not find a default branch for project ${projectId}.`);
+        }
+        return only.id;
+    }
+    const picked = await pickBranchInteractively(branches, {
+        message: 'Which branch would you like to link?',
+        nonInteractiveMessage: 'No branch could be selected without an interactive terminal. ' +
+            'Re-run `neonctl link` interactively, or `neonctl checkout <branch>` to pin one.',
+    });
+    if (picked.kind === 'existing') {
+        return picked.branchId;
+    }
+    return createBranch(props.apiClient, projectId, picked.name, branches);
+};
 const fetchRegions = async (props) => {
     try {
         const { data } = await props.apiClient.getActiveRegions();
@@ -646,6 +696,20 @@ const printHumanSummary = (_props, summary) => {
     lines.push('');
     process.stdout.write(`${lines.join('\n')}\n`);
 };
+/**
+ * Print the link summary, then run the bundled `env pull` so a human `link` ends with the
+ * branch's connection string already on disk — the branch-first loop is just link + checkout.
+ * `--no-env-pull` opts out (env pull's own status / skip hint is logged to stderr).
+ */
+const finalizeHumanLink = async (props, summary) => {
+    printHumanSummary(props, summary);
+    await autoPullEnvAfterPin({
+        ...props,
+        projectId: summary.projectId,
+        branch: summary.branchId,
+        envPull: props.envPull,
+    });
+};
 const onPromptState = (state) => {
     if (state.aborted) {
         process.stdout.write('\x1B[?25h');

package/config_format.js

@@ -0,0 +1,66 @@
+/**
+ * Render a TTL in whole seconds back to the canonical `neon.ts` duration string (e.g.
+ * `604800` -> `"7d"`), falling back to seconds when no clean unit boundary matches. Mirrors
+ * the formatter `@neondatabase/config` uses when it emits a TTL, so `config status` shows
+ * the same value a user would write in `neon.ts`.
+ */
+export const formatDurationSeconds = (totalSeconds) => {
+    const units = [
+        ['w', 7 * 24 * 60 * 60],
+        ['d', 24 * 60 * 60],
+        ['h', 60 * 60],
+        ['m', 60],
+    ];
+    for (const [unit, perUnit] of units) {
+        if (totalSeconds % perUnit === 0)
+            return `${totalSeconds / perUnit}${unit}`;
+    }
+    return `${totalSeconds}s`;
+};
+/**
+ * Project a resolved branch config (plus the separately-pulled preview state, since
+ * functions/buckets don't live on the closure) into a {@link NeonConfigView}.
+ *
+ * - Service toggles are surfaced as `true` only when enabled (disabled is the absence of
+ *   the key, exactly as in `neon.ts`).
+ * - `ttlSeconds` is rendered back to a duration string (`7d`).
+ * - The `branch` section is the JSON-able part of what would otherwise be the `branch`
+ *   closure: `parent` / `ttl` / `protected` / `postgres.computeSettings`.
+ * - `branch` and `preview` are omitted entirely when they would be empty.
+ */
+export const toNeonConfigView = (resolved, preview) => {
+    const view = {};
+    if (resolved.authEnabled)
+        view.auth = true;
+    if (resolved.dataApiEnabled)
+        view.dataApi = true;
+    const previewView = toPreviewView(preview);
+    if (previewView)
+        view.preview = previewView;
+    const branch = {};
+    if (resolved.parent !== undefined)
+        branch.parent = resolved.parent;
+    if (resolved.ttlSeconds !== undefined)
+        branch.ttl = formatDurationSeconds(resolved.ttlSeconds);
+    if (resolved.protected !== undefined)
+        branch.protected = resolved.protected;
+    if (resolved.postgres?.computeSettings)
+        branch.postgres = resolved.postgres;
+    if (Object.keys(branch).length > 0)
+        view.branch = branch;
+    return view;
+};
+const toPreviewView = (preview) => {
+    if (!preview)
+        return undefined;
+    const out = {};
+    if (preview.aiGatewayEnabled)
+        out.aiGateway = true;
+    if (preview.functions.length > 0) {
+        out.functions = Object.fromEntries(preview.functions.map((fn) => [fn.slug, { name: fn.name }]));
+    }
+    if (preview.buckets.length > 0) {
+        out.buckets = Object.fromEntries(preview.buckets.map((b) => [b.name, { access: b.access }]));
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+};

package/dev/env.js

@@ -0,0 +1,199 @@
+import { loadConfigFromFile, } from '@neondatabase/config';
+import { plan, pullConfig, } from '@neondatabase/config-runtime';
+import { fetchEnv, toEntries } from '@neondatabase/env';
+import { log } from '../log.js';
+/**
+ * Thrown when a `neon.ts` policy declares a branch-level resource (Neon Auth,
+ * Data API, a bucket, the AI Gateway) that the linked remote branch does not
+ * have yet. Unlike every other failure in {@link resolveDevEnv} — which degrades
+ * to "run without injection" — this is a hard stop: the user's intent (a policy)
+ * cannot be honored, and silently dropping the secret would be more confusing
+ * than refusing to start. The fix is to provision the resource first.
+ */
+export class DevEnvMismatchError extends Error {
+    constructor() {
+        super(...arguments);
+        this.name = 'DevEnvMismatchError';
+    }
+}
+/**
+ * Signals that no project/branch context could be resolved, so there is nothing to
+ * resolve env from. `resolveDevEnv` degrades on this (dev runs without injection);
+ * `env pull` surfaces it (an explicit pull needs a branch).
+ */
+export class MissingBranchContextError extends Error {
+    constructor() {
+        super(...arguments);
+        this.name = 'MissingBranchContextError';
+    }
+}
+/**
+ * Resolve the branch's Neon env vars (pooled / direct `DATABASE_URL`, plus Auth /
+ * Data API when enabled) into a `{ KEY: value }` map. Shared by `neon dev` (which
+ * injects them) and `neon env pull` (which writes them to a `.env` file).
+ *
+ * Tiered:
+ *
+ *   1. a `neon.ts` policy is found -> the policy is the source of truth. We first
+ *      check it against the branch's live state (`plan`); if it declares a resource
+ *      the branch is missing, we stop with a {@link DevEnvMismatchError} pointing at
+ *      `neonctl deploy`. Otherwise `fetchEnv` evaluates the policy.
+ *   2. no `neon.ts`, but a project + branch are known -> `pullConfig` reads the
+ *      branch's live state (incl. Auth / Data API enablement) into a config, then
+ *      `fetchEnv` resolves what is actually enabled.
+ *   3. otherwise -> throw {@link MissingBranchContextError}.
+ *
+ * Unlike {@link resolveDevEnv}, this never swallows errors — callers decide how to
+ * handle them.
+ */
+export const resolveNeonEnvVars = async (ctx) => {
+    const config = await loadNeonConfig(ctx.cwd);
+    if (config) {
+        if (!ctx.projectId || !ctx.branchId) {
+            throw new MissingBranchContextError('Found a neon.ts but could not resolve the project/branch. ' +
+                'Run `neonctl link` and `neonctl checkout <branch>`, or pass ' +
+                '--project-id / --branch.');
+        }
+        // Resolve env from the policy with its `preview.functions` removed. Functions carry no
+        // branch-level secrets — their env comes from the local `neon.ts` `functions.<slug>.env`,
+        // layered per-function by the dev server — so env resolution never needs the functions
+        // API. Probing it (via `plan`/`fetchEnv`) only adds a failure mode: an undeployed
+        // function, or a project where the Functions Preview isn't enabled, would error and sink
+        // ALL injection (including DATABASE_URL). Stripping functions keeps env resolution honest
+        // while leaving buckets / AI Gateway / Auth / Data API fully checked — those DO carry
+        // secrets, so a declared-but-missing one still hard-stops (see assertPolicyMatchesBranch).
+        const envConfig = withoutPreviewFunctions(config);
+        await assertPolicyMatchesBranch(envConfig, ctx);
+        return await fetchAndProject(envConfig, ctx);
+    }
+    if (ctx.projectId && ctx.branchId) {
+        const pulled = await pullConfig({
+            projectId: ctx.projectId,
+            branchId: ctx.branchId,
+            ...(ctx.apiKey ? { apiKey: ctx.apiKey } : {}),
+            ...(ctx.api ? { api: ctx.api } : {}),
+        });
+        // `pulled.config` is already a `Config` (static auth/dataApi toggles + a branch
+        // tuning closure), so it feeds straight into fetchEnv — no wrapping needed.
+        return await fetchAndProject(pulled.config, ctx);
+    }
+    throw new MissingBranchContextError('No project/branch context found. Link a branch (`neonctl link` / ' +
+        '`neonctl checkout`) or pass --project-id and --branch.');
+};
+/**
+ * `neon dev`'s env resolver: {@link resolveNeonEnvVars} with graceful degradation.
+ *
+ * - Success → `{ vars }` (possibly just the always-present Postgres URLs).
+ * - No linked branch / project → `{ vars: {}, skipped }` with a "link a branch" hint; the
+ *   function still runs locally, just without Neon env.
+ * - Any other failure (offline, transient API error) → `{ vars: {}, skipped }` naming the
+ *   cause; again non-fatal.
+ * - {@link DevEnvMismatchError} (policy declares a secret-bearing service the branch lacks)
+ *   is the one hard stop and is re-thrown for the caller to surface.
+ */
+export const resolveDevEnv = async (ctx) => {
+    try {
+        return { vars: await resolveNeonEnvVars(ctx) };
+    }
+    catch (err) {
+        if (err instanceof DevEnvMismatchError)
+            throw err;
+        if (err instanceof MissingBranchContextError) {
+            log.debug('dev: %s; skipping env injection', err.message);
+            return {
+                vars: {},
+                skipped: {
+                    reason: 'no linked Neon branch — run `neonctl link`, then ' +
+                        '`neonctl checkout <branch>`, to inject DATABASE_URL and friends',
+                },
+            };
+        }
+        const detail = err instanceof Error ? err.message : String(err);
+        log.debug('dev: env resolution failed: %s', detail);
+        return {
+            vars: {},
+            skipped: {
+                reason: `could not reach Neon (${detail}); running without Neon env`,
+            },
+        };
+    }
+};
+/**
+ * Return the policy with its `preview.functions` removed, so the env path never enumerates
+ * functions against the Neon API. Functions are local-source-bundled and produce no
+ * branch-level secrets, so they are irrelevant to env resolution; probing them only risks
+ * failing the whole resolve (undeployed function, or Functions Preview disabled on the
+ * project). Buckets / AI Gateway and the top-level Auth / Data API toggles are preserved —
+ * they DO carry env, so they must still be checked and resolved. Returns the config
+ * unchanged when it declares no functions.
+ */
+const withoutPreviewFunctions = (config) => {
+    const preview = config.preview;
+    if (!preview?.functions)
+        return config;
+    const previewWithoutFunctions = { ...preview };
+    delete previewWithoutFunctions.functions;
+    return { ...config, preview: previewWithoutFunctions };
+};
+/**
+ * Tier-1 guard. Dry-run the policy against the branch's live state and stop if
+ * it declares a branch-level resource the branch is missing. Built on `plan` so
+ * it covers every present and future provisionable resource for free: any
+ * `create` action is a resource `neonctl deploy` would provision.
+ *
+ * Called with functions already stripped (see {@link withoutPreviewFunctions}), so the
+ * `plan` probe never enumerates the functions API — an undeployed function, or a project
+ * without the Functions Preview, must never block local dev or sink env injection.
+ */
+const assertPolicyMatchesBranch = async (config, ctx) => {
+    const result = await plan(config, {
+        projectId: ctx.projectId,
+        branchId: ctx.branchId,
+        ...(ctx.apiKey ? { apiKey: ctx.apiKey } : {}),
+        ...(ctx.api ? { api: ctx.api } : {}),
+    });
+    const missing = result.applied.filter(isMissingResource);
+    if (missing.length === 0)
+        return;
+    const names = missing.map((change) => change.identifier).join(', ');
+    throw new DevEnvMismatchError(`Your neon.ts declares ${names} for branch ${ctx.branchId}, but the branch ` +
+        'does not have it yet, so the matching env vars cannot be injected. ' +
+        'Provision it first with `neonctl deploy` (or `neonctl config apply`), ' +
+        'then re-run `neonctl dev`.');
+};
+/**
+ * A planned change that provisions a branch-level resource the branch lacks: a
+ * `create` on a service (Neon Auth, Data API, a bucket, the AI Gateway). Branch
+ * setting drift (`update`) and `noop`s are ignored — they don't block local dev
+ * — and functions are excluded (see {@link assertPolicyMatchesBranch}).
+ */
+const isMissingResource = (change) => change.kind === 'service' &&
+    change.action === 'create' &&
+    !change.identifier.startsWith('function:');
+const fetchAndProject = async (config, ctx) => {
+    const env = await fetchEnv(config, {
+        projectId: ctx.projectId,
+        branchId: ctx.branchId,
+        ...(ctx.apiKey ? { apiKey: ctx.apiKey } : {}),
+        ...(ctx.api ? { api: ctx.api } : {}),
+    });
+    return toEntries(env);
+};
+/**
+ * Load a `neon.ts` policy if one exists on the path from `cwd` up to the repo
+ * root. Returns `null` when there is none (the common "no config" case), and
+ * surfaces real load errors (e.g. a syntax error in an existing file).
+ */
+const loadNeonConfig = async (cwd) => {
+    try {
+        const { config } = await loadConfigFromFile({ cwd });
+        return config;
+    }
+    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;
+    }
+};