neonctl 2.24.1 → 2.24.2

package/README.md

@@ -166,7 +166,7 @@ step to pick which branch to pin — the same `＋ Create a new branch…` + lis
 ```bash
 ? Which organization would you like to link? › Personal Org (org-abc123)
 ? Which project would you like to link? › my-app (polished-snowflake-12345678)
-? Which branch would you like to link? › ✱ main (br-main-branch-87654321)
+? Which branch would you like to link? › [default] main (br-main-branch-87654321)
 ```
 
 **Non-interactive (flags or `--params` JSON)** — for scripts and CI:

package/commands/checkout.js

@@ -7,7 +7,7 @@ import { createBranch, pickBranchInteractively, } from '../utils/branch_picker.j
 import { fillSingleProject } from '../utils/enrichers.js';
 import { looksLikeBranchId } from '../utils/formats.js';
 import { autoPullEnvAfterPin } from './env.js';
-import { applyPolicyOnCreate } from './config.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.
@@ -52,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`
@@ -64,15 +64,17 @@ 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
@@ -94,26 +96,27 @@ const resolveBranchId = async (props, projectId) => {
                 '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.apiClient, 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) {
@@ -129,9 +132,33 @@ 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.apiClient, 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

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

@@ -56,6 +56,7 @@ const runSingleSource = async (props) => {
         ...(props.projectId ? { projectId: props.projectId } : {}),
         ...(branchId ? { branchId } : {}),
         ...(props.apiKey ? { apiKey: props.apiKey } : {}),
+        ...(props.apiHost ? { apiHost: props.apiHost } : {}),
     });
     const unit = {
         slug: null,
@@ -93,6 +94,7 @@ const runFromConfig = async (props) => {
         ...(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

package/commands/env.js

@@ -49,6 +49,7 @@ 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);

package/dev/env.js

@@ -2,6 +2,12 @@ import { loadConfigFromFile, } from '@neondatabase/config';
 import { plan, pullConfig, } from '@neondatabase/config-runtime';
 import { fetchEnv, toEntries } from '@neondatabase/env';
 import { log } from '../log.js';
+/** The API-targeting options every runtime call forwards from the context. */
+const apiOptions = (ctx) => ({
+    ...(ctx.apiKey ? { apiKey: ctx.apiKey } : {}),
+    ...(ctx.apiHost ? { apiHost: ctx.apiHost } : {}),
+    ...(ctx.api ? { api: ctx.api } : {}),
+});
 /**
  * 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
@@ -70,8 +76,7 @@ export const resolveNeonEnvVars = async (ctx) => {
         const pulled = await pullConfig({
             projectId: ctx.projectId,
             branchId: ctx.branchId,
-            ...(ctx.apiKey ? { apiKey: ctx.apiKey } : {}),
-            ...(ctx.api ? { api: ctx.api } : {}),
+            ...apiOptions(ctx),
         });
         // `pulled.config` is already a `Config` (static auth/dataApi toggles + a branch
         // tuning closure), so it feeds straight into fetchEnv — no wrapping needed.
@@ -149,8 +154,7 @@ 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 } : {}),
+        ...apiOptions(ctx),
     });
     const missing = result.applied.filter(isMissingResource);
     if (missing.length === 0)
@@ -174,8 +178,7 @@ 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 } : {}),
+        ...apiOptions(ctx),
     });
     return toEntries(env);
 };

package/package.json

@@ -5,7 +5,7 @@
     "url": "git+ssh://git@github.com/neondatabase/neonctl.git"
   },
   "type": "module",
-  "version": "2.24.1",
+  "version": "2.24.2",
   "description": "CLI tool for NeonDB Cloud management",
   "main": "index.js",
   "author": "NeonDB",
@@ -59,9 +59,9 @@
   "dependencies": {
     "@hono/node-server": "2.0.4",
     "@neondatabase/api-client": "2.7.1",
-    "@neondatabase/config": "0.4.0",
-    "@neondatabase/config-runtime": "0.4.0",
-    "@neondatabase/env": "0.3.0",
+    "@neondatabase/config": "0.4.2",
+    "@neondatabase/config-runtime": "0.4.2",
+    "@neondatabase/env": "0.3.2",
     "@segment/analytics-node": "1.3.0",
     "axios": "1.7.2",
     "axios-debug-log": "1.0.0",

package/utils/branch_picker.js

@@ -5,6 +5,21 @@ import { log } from '../log.js';
 import { isCi } from '../env.js';
 /** Sentinel `value` for the "create a new branch" choice (no branch id can collide). */
 const CREATE_BRANCH_CHOICE = Symbol('create-branch');
+/**
+ * Render a branch's display name with the same word labels as `neonctl branch list`
+ * (`[default]`, `[protected]`) instead of symbols, so the picker reads clearly.
+ */
+const branchLabel = (branch) => {
+    const labels = [];
+    if (branch.default) {
+        labels.push('[default]');
+    }
+    if (branch.protected) {
+        labels.push('[protected]');
+    }
+    labels.push(branch.name);
+    return labels.join(' ');
+};
 /**
  * Prompt the user to pick a branch from `branches`, with a "＋ Create a new branch…" option
  * pinned to the top (mirroring the project/org pickers). The default selection is the
@@ -27,7 +42,7 @@ export const pickBranchInteractively = async (branches, opts) => {
         choices: [
             { title: '＋ Create a new branch…', value: CREATE_BRANCH_CHOICE },
             ...branches.map((b) => ({
-                title: `${b.default ? '✱ ' : ''}${b.name} (${b.id})`,
+                title: `${branchLabel(b)} (${b.id})`,
                 value: b.id,
             })),
         ],