neonctl 2.36.1 → 2.37.0

package/dist/commands/checkout.js

@@ -60,7 +60,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, branchName, created, policyApplied } = await resolveBranchId(props, projectId);
+    const { branchId, branchName, created, policyApplied, policyFailure } = await resolveBranchId(props, projectId);
     const orgId = await resolveOrgId(props, projectId);
     // `checkout` is a thin helper over `link`. It fully "heals" the context file:
     // it always (re)writes `projectId`, `branch`, and `orgId` (when the project
@@ -78,14 +78,17 @@ export const handler = async (props) => {
     // 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({
+    const failure = created && !policyApplied
+        ? await applyPolicyOrDescribeFailure({
             projectId,
             branchId,
             ...(props.apiKey ? { apiKey: props.apiKey } : {}),
             ...(props.apiHost ? { apiHost: props.apiHost } : {}),
-        });
-    }
+            ...(props.color !== undefined
+                ? { color: props.color }
+                : {}),
+        })
+        : policyFailure;
     // 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({
@@ -94,6 +97,31 @@ export const handler = async (props) => {
         branch: branchId,
         envPull: props.envPull,
     });
+    // A policy that didn't fully apply is reported last, after the pin and the env pull, so the
+    // created branch is left in a consistent, usable, re-runnable state: the failure is what
+    // needs fixing, not the checkout. Still a non-zero exit — the branch does not match the
+    // policy, and `checkout` will not reconcile it on a second run.
+    if (failure) {
+        throw new Error([
+            `Branch ${branchName} (${branchId}) was created and checked out, but applying neon.ts to it failed: ${failure}`,
+            "The branch is usable but does not match the policy, and `neonctl checkout` never reconciles a branch that already exists.",
+            `Fix the cause above, then run \`neonctl deploy --update-existing\` to apply the policy to it — or, if your policy only configures new branches (keyed on \`!branch.exists\`), delete the branch and check it out again: \`neonctl branches delete ${branchName}\` then \`neonctl checkout ${branchName}\`.`,
+        ].join("\n"));
+    }
+};
+/**
+ * Apply the policy to a branch `checkout` just created bare, returning the failure message
+ * instead of throwing it. The branch and the context pin already stand at this point, so a
+ * failed apply must not abort the rest of the checkout — the handler reports it at the end.
+ */
+const applyPolicyOrDescribeFailure = async (props) => {
+    try {
+        await applyPolicyOnCreate(props);
+        return undefined;
+    }
+    catch (err) {
+        return err instanceof Error ? err.message : String(err);
+    }
 };
 const resolveBranchId = async (props, projectId) => {
     const branches = (await props.apiClient.listProjectBranches({ projectId }))
@@ -168,6 +196,7 @@ const createCheckoutBranch = async (props, projectId, name, branches) => {
         branchName: name,
         ...(props.apiKey ? { apiKey: props.apiKey } : {}),
         ...(props.apiHost ? { apiHost: props.apiHost } : {}),
+        ...(props.color !== undefined ? { color: props.color } : {}),
     });
     if (fromPolicy) {
         return {
@@ -175,6 +204,9 @@ const createCheckoutBranch = async (props, projectId, name, branches) => {
             branchName: name,
             created: true,
             policyApplied: true,
+            ...(fromPolicy.policyFailure
+                ? { policyFailure: fromPolicy.policyFailure }
+                : {}),
         };
     }
     return {

package/dist/commands/config.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { resolveConfig } from "@neon/config";
-import { apply, createBranch as createBranchFromPolicy, inspect, loadConfigFromFile, PushConflictError, plan, } from "@neon/config-runtime";
+import { apply, createBranch as createBranchFromPolicy, inspect, isPartialBranchCreateError, loadConfigFromFile, PushConflictError, plan, } from "@neon/config-runtime";
 import chalk from "chalk";
 import { getApiClient } from "../api.js";
 import { toNeonConfigView } from "../config_format.js";
@@ -548,16 +548,21 @@ export const applyPolicyOnCreate = async (props) => {
         allowProtectedBranch: true,
         bundleFunction: neonctlBundler,
     });
-    logPolicyResult(result);
+    logPolicyResult(result, { color: props.color !== false });
 };
-/** Log a one-line summary of what applying a `neon.ts` policy changed (or that nothing did). */
-const logPolicyResult = (result) => {
+/**
+ * Report what applying a `neon.ts` policy changed, using the same `field → value` diff
+ * `deploy` prints (see {@link renderAppliedChanges}) rather than a bare list of change
+ * identifiers — the identifier alone repeats the branch name once per change and never says
+ * *what* was applied, which is the only interesting part on a freshly created branch.
+ */
+const logPolicyResult = (result, opts) => {
     const changes = result.applied.filter((c) => c.action !== "noop");
     if (changes.length === 0) {
         log.info("neon.ts applied — no changes were needed.");
         return;
     }
-    log.info("neon.ts applied — %d change%s: %s", changes.length, changes.length === 1 ? "" : "s", changes.map((c) => `${c.action} ${c.identifier}`).join(", "));
+    log.info("%s", renderAppliedChanges(changes, `neon.ts applied — ${changes.length} change${changes.length === 1 ? "" : "s"}:`, opts));
 };
 /**
  * Create a branch **from** the local `neon.ts` policy. Returns `null` when there is no
@@ -570,6 +575,10 @@ const logPolicyResult = (result) => {
  * 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.
+ *
+ * A branch that was created but whose policy failed to apply is reported through
+ * `policyFailure` rather than thrown: the branch is real, so `checkout` still needs to pin it
+ * (see the handler) instead of leaving it stranded behind an unchanged `.neon`.
  */
 export const createBranchFromPolicyOnCheckout = async (props) => {
     let config;
@@ -591,15 +600,27 @@ export const createBranchFromPolicyOnCheckout = async (props) => {
         ...(props.runtimeApi ? { runtimeApi: props.runtimeApi } : {}),
         config,
     });
-    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 };
+    try {
+        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, { color: props.color !== false });
+        return { branchId };
+    }
+    catch (err) {
+        // The branch exists but its policy didn't fully apply. Hand the id back so checkout
+        // pins it and reports the failure with the remediation, rather than aborting with an
+        // unpinned context and a branch the next `checkout` would silently accept as-is.
+        if (isPartialBranchCreateError(err)) {
+            log.info("Created branch %s (%s) from neon.ts policy.", err.branchName, err.branchId);
+            return { branchId: err.branchId, policyFailure: err.reason };
+        }
+        throw err;
+    }
 };

package/dist/commands/env.js

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import { NEON_ENV_VAR_KEYS } from "@neon/env";
 import chalk from "chalk";
+import { ensureGitignored } from "../context.js";
 import { resolveNeonEnvVars } from "../dev/env.js";
 import { mergeEnvFile, readEnvFile, resolveEnvFilePath } from "../env_file.js";
 import { log } from "../log.js";
@@ -76,7 +77,8 @@ export const pull = async (props, opts = {}) => {
     // keys and the unified branch credential's `api_token` / `s3_secret_access_key`, which the
     // API returns exactly once — instead of minting a fresh credential on every pull.
     const targetPath = resolveEnvFilePath(cwd, props.file);
-    const existingEnv = existsSync(targetPath) ? readEnvFile(targetPath) : {};
+    const fileExisted = existsSync(targetPath);
+    const existingEnv = fileExisted ? readEnvFile(targetPath) : {};
     // 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.
@@ -105,6 +107,13 @@ export const pull = async (props, opts = {}) => {
     if (removed.length > 0) {
         log.info("Removed %d stale Neon variable%s not enabled on this branch: %s", removed.length, removed.length === 1 ? "" : "s", removed.join(", "));
     }
+    // A dotenv file *we* create holds live branch credentials (DATABASE_URL, Auth keys, service
+    // tokens), so ignore it the same way the `.neon` context file is — otherwise a fresh repo is
+    // one `git add -A` away from committing them. Only on creation: re-adding the entry on every
+    // pull would fight a user who deliberately un-ignored a file they want to commit.
+    if (!fileExisted) {
+        ensureGitignored(targetPath);
+    }
     // When the branch has the AI Gateway enabled, the pulled credentials always work, but
     // serving is plan-gated and the model set can be reduced on the beta — surface that as a
     // courtesy notice (best-effort; never fails the pull). The freshly pulled token lets us

package/dist/context.js

@@ -153,9 +153,12 @@ export const setContext = (file, context) => {
     });
 };
 /**
- * Make sure the `.gitignore` next to `file` lists the file's basename
- * (currently always `.neon`). Creates the `.gitignore` if it doesn't exist,
- * or appends `.neon` if it's missing — never duplicates an existing entry.
+ * Make sure the `.gitignore` next to `file` covers the file's basename — used for the `.neon`
+ * context file and for a `.env` we create (both carry credentials that must not be committed).
+ * Creates the `.gitignore` if it doesn't exist, otherwise appends the entry only when nothing
+ * there already covers it: an exact line, or a basename glob such as `.env*` / `*.local`
+ * (see {@link gitignoreCovers}), so a repo that already ignores env files doesn't collect a
+ * redundant line per pull.
  *
  * Best-effort: a failure here (e.g. read-only filesystem) is logged at debug
  * level and swallowed; persisting the context file is the primary goal and
@@ -188,5 +191,41 @@ const basenameOf = (file) => {
     return parts[parts.length - 1] || CONTEXT_FILE;
 };
 const hasGitignoreEntry = (content, entry) => {
-    return content.split(/\r?\n/).some((line) => line.trim() === entry);
+    return content
+        .split(/\r?\n/)
+        .some((line) => gitignoreCovers(line.trim(), entry));
+};
+/**
+ * Whether a single `.gitignore` line already ignores `entry` (a bare basename like `.neon` or
+ * `.env.local`).
+ *
+ * Deliberately narrow: an exact match, or a glob **without a path separator** — the
+ * `.env*` / `*.local` / `.env.?` shapes that repos actually use for env files — matched
+ * against the whole basename. Everything else returns false, which at worst appends an entry
+ * git already covers (harmless) rather than skipping one it doesn't (a committed credential).
+ * That's why path-scoped patterns (`config/.env`), negations (`!.env.local`), character
+ * classes, and comments are all treated as "does not cover".
+ */
+const gitignoreCovers = (line, entry) => {
+    if (line === "" || line.startsWith("#") || line.startsWith("!")) {
+        return false;
+    }
+    // A trailing slash marks a directory-only pattern; the leading one anchors to the
+    // .gitignore's own directory, which is exactly where `entry` lives.
+    const pattern = line.replace(/\/$/, "").replace(/^\//, "");
+    if (pattern === entry)
+        return true;
+    if (pattern.includes("/") || pattern.includes("["))
+        return false;
+    if (!pattern.includes("*") && !pattern.includes("?"))
+        return false;
+    return globToRegExp(pattern).test(entry);
+};
+/** Compile a separator-free `.gitignore` glob (`*` / `?` only) into an anchored RegExp. */
+const globToRegExp = (pattern) => {
+    const source = pattern
+        .replace(/[.+^${}()|\\]/g, "\\$&")
+        .replace(/\*/g, "[^/]*")
+        .replace(/\?/g, "[^/]");
+    return new RegExp(`^${source}$`);
 };

package/dist/utils/config_diff.js

@@ -97,14 +97,20 @@ const serviceLabel = (identifier) => {
 /**
  * The desired-only field changes for an applied/planned **branch** update. The
  * synthesized `AppliedChange.details` carry the new value keyed by `field`
- * (`ttl`→`expiresAt`, `protected`→`protected`, `computeSettings`→`settings`);
- * the previous value isn't threaded through in Phase 1, so these render as
- * `field → desired` (no red "before"). Object settings expand into sub-fields.
+ * (`parent`→`parent`, `ttl`→`expiresAt`, `protected`→`protected`,
+ * `computeSettings`→`settings`); the previous value isn't threaded through in
+ * Phase 1, so these render as `field → desired` (no red "before"). Object
+ * settings expand into sub-fields.
+ *
+ * `parent` only ever arrives from a branch creation (it cannot be changed
+ * afterwards), where it reports the parent the policy named.
  */
 const appliedBranchFields = (change) => {
     const details = change.details ?? {};
     const field = typeof details.field === "string" ? details.field : "setting";
     switch (field) {
+        case "parent":
+            return expandField("parent", undefined, details.parent);
         case "ttl":
             return expandField("ttl", undefined, details.expiresAt);
         case "protected":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neonctl",
-  "version": "2.36.1",
+  "version": "2.37.0",
   "description": "CLI tool for Neon Serverless Postgres",
   "keywords": [
     "neon",
@@ -51,10 +51,10 @@
     "which": "3.0.1",
     "yaml": "^2.9.0",
     "yargs": "17.7.2",
-    "@neon/sdk": "1.3.0",
-    "@neon/config": "0.9.6",
-    "@neon/env": "0.11.6",
-    "@neon/config-runtime": "0.9.7"
+    "@neon/config": "0.10.0",
+    "@neon/config-runtime": "0.10.0",
+    "@neon/env": "0.11.8",
+    "@neon/sdk": "1.3.0"
   },
   "optionalDependencies": {
     "esbuild": "0.28.1"
@@ -111,7 +111,7 @@
     "typecheck": "tsc --noEmit",
     "lint": "pnpm typecheck && biome check src",
     "lint:fix": "pnpm typecheck && biome check src --write",
-    "test": "pnpm build && vitest run",
+    "test": "pnpm --filter neonctl... build && vitest run",
     "test:ci": "pnpm build && vitest run",
     "test:conformance": "vitest run --config tests/psql-conformance/vitest.config.ts"
   }