neonctl 2.23.1 → 2.24.0

package/README.md

@@ -147,7 +147,7 @@ There are three modes:
 ```bash
 $ neonctl link
 ? Which organization would you like to link? › Personal Org (org-abc123)
-? Which project would you like to link? › + Create new project
+? Which project would you like to link? › ＋ Create new project…
 ? Name for the new project: › my-app
 ? Which region should the new project run in? › AWS US East (Ohio) (aws-us-east-2)
 Created project polished-snowflake-12345678 ("my-app") in aws-us-east-2.
@@ -269,6 +269,63 @@ $ cat .neon
 
 **`.gitignore` scaffolding**: when `.neon` is **created** for the first time, the CLI also makes sure a `.gitignore` sits alongside it listing `.neon`. If `.gitignore` doesn't exist it's created with a single `.neon` line; if it does exist, `.neon` is appended only when missing (no duplicates, your other entries are left alone). On subsequent updates to an existing `.neon`, `.gitignore` is left untouched — so if you deliberately un-ignore `.neon` (e.g. to commit shared context), the entry is not re-added on every command.
 
+## Config as code (`config` / `deploy`)
+
+Describe a branch's desired state in a `neon.ts` policy and reconcile it from the CLI — the Neon equivalent of `terraform status` / `plan` / `apply`. The policy is a function of the branch it's being evaluated for; you switch on the branch (`name`, `isDefault`, …) and return the config you want (auth, Data API, compute settings, TTL, protection, and Preview features like Functions and buckets):
+
+```ts
+// neon.ts
+import { defineConfig } from '@neondatabase/config/v1';
+
+export default defineConfig((branch) => {
+  if (branch.isDefault) {
+    return { protected: true, auth: {} };
+  }
+  return { parent: 'main', ttl: '7d' };
+});
+```
+
+Three sub-commands plus a top-level alias drive it:
+
+```bash
+# Inspect the branch's live Neon state (read-only — never mutates)
+neon config status
+
+# Dry-run diff: show exactly what `apply` would change
+neon config plan
+
+# Reconcile the policy against the branch
+neon config apply
+
+# `neon deploy` is an alias for `neon config apply`
+neon deploy
+```
+
+**Project & branch resolution** follows the same chain as the rest of the CLI, each entry winning over the next:
+
+1. `--project-id <id>` flag
+2. `projectId` from the closest `.neon` file (found by walking up from the current directory — see "Where `.neon` lives" above)
+3. If still unresolved and the API key maps to exactly one project, that project is auto-detected
+
+The branch is chosen with `--branch <id|name>`; without it the project's default branch is used. The policy itself is found by walking up from the current directory for a `neon.ts`, or pass `--config <path>` to point at one explicitly.
+
+**Apply-only flags** (also available on `deploy`):
+
+- `--update-existing` — auto-confirm overriding existing remote settings on the branch. Without it, drift on settings already present remotely (compute, TTL, `protected`) is reported as a **conflict** and `apply` makes no changes until you resolve it or pass this flag.
+- `--allow-protected` — auto-confirm applying to a branch Neon marks as protected. Without it, `apply` refuses to touch a protected branch.
+
+**Output**: `status` prints the project, branch, and reverse-engineered config; `plan` / `apply` print the planned/applied changes and any conflicts as tables. Pass `--output json` (or `--output yaml`) to emit the full machine-readable result (`PushResult`) for piping into other tools or CI.
+
+```bash
+# CI gate: fail the build if the branch has drifted from the policy
+neon config plan --project-id polished-snowflake-12345678 --output json
+
+# Reconcile a feature branch, overriding any manual tweaks made in the console
+neon deploy --branch my-feature --update-existing
+```
+
+Function deploys declared under `preview.functions` are bundled by neonctl's own esbuild helper and uploaded as part of `apply`, so the policy stays declarative and the packaged CLI never has to embed esbuild's native binary.
+
 ## Commands
 
 | Command                                                                    | Subcommands                                                                                 | Description                    |
@@ -287,6 +344,8 @@ $ cat .neon
 | [set-context](https://neon.com/docs/reference/cli-set-context)             |                                                                                             | Set context for session        |
 | checkout                                                                   |                                                                                             | Pin a branch in `.neon`        |
 | [link](https://neon.com/docs/reference/cli-link)                           |                                                                                             | Link a directory to a project  |
+| config                                                                     | `status`, `plan`, `apply`                                                                   | Drive a branch from `neon.ts`  |
+| deploy                                                                     |                                                                                             | Alias for `config apply`       |
 | [completion](https://neon.com/docs/reference/cli-completion)               |                                                                                             | Generate a completion script   |
 
 ## Global options

package/commands/auth.js

@@ -100,6 +100,11 @@ export const ensureAuth = async (props) => {
     if (props._.length === 0 || props.help) {
         return;
     }
+    // `dev` runs a function locally. It injects the selected branch's env vars
+    // when credentials happen to be available, but must never trigger an
+    // interactive login: use an API key or existing stored credentials if
+    // present, otherwise run with no API client (env injection is skipped).
+    const isLocalDev = props._[0] === 'dev';
     // Use existing API key or handle auth command
     if (props.apiKey || props._[0] === 'auth') {
         if (props.apiKey) {
@@ -141,6 +146,13 @@ export const ensureAuth = async (props) => {
     else {
         log.debug('Credentials file %s does not exist, starting authentication', credentialsPath);
     }
+    // `dev` never launches the interactive browser flow. With no usable
+    // credentials it proceeds without an API client; env injection is skipped
+    // and the function still runs locally.
+    if (isLocalDev) {
+        log.debug('dev: no usable credentials; running without env injection');
+        return;
+    }
     // Start new auth flow if no valid token exists or refresh failed
     const apiKey = await authFlow(props);
     props.apiKey = apiKey;

package/commands/checkout.js

@@ -7,6 +7,7 @@ import { isCi } from '../env.js';
 import { log } from '../log.js';
 import { fillSingleProject } from '../utils/enrichers.js';
 import { looksLikeBranchId } from '../utils/formats.js';
+import { applyPolicyOnCreate } 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.
@@ -44,7 +45,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 = await resolveBranchId(props, projectId);
+    const { branchId, created } = 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`
@@ -56,36 +57,44 @@ 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) {
+        await applyPolicyOnCreate({
+            projectId,
+            branchId,
+            ...(props.apiKey ? { apiKey: props.apiKey } : {}),
+        });
+    }
 };
-/**
- * Resolve the branch id to check out.
- *
- * - Branch **id** (`br-…`): looked up by id. A non-existent id is a hard "not
- *   found" error — we never offer to create one, since ids are server-assigned.
- * - Branch **name**: looked up by name. If it doesn't exist, in an interactive
- *   terminal we offer to create it (like `neonctl branch create --name <name>`);
- *   in a non-interactive context it's the usual "not found" error.
- * - **Omitted**: open an interactive picker listing the project's branches (TTY
- *   only); in a non-interactive context a missing branch is a hard error.
- */
 const resolveBranchId = async (props, projectId) => {
     const branches = (await props.apiClient.listProjectBranches({ projectId }))
         .data.branches;
     if (!props.id) {
-        return pickBranchInteractively(branches, projectId);
+        const picked = await pickBranchInteractively(branches);
+        if (picked.kind === 'existing') {
+            return { branchId: picked.branchId, created: false };
+        }
+        // The user chose "create a new branch" from the picker.
+        return {
+            branchId: await createBranch(props, projectId, picked.name, branches),
+            created: true,
+        };
     }
     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 byId.id;
+            return { branchId: byId.id, created: false };
         }
         throw new Error(notFoundMessage(ref, branches));
     }
     const byName = branches.find((b) => b.name === ref);
     if (byName) {
-        return byName.id;
+        return { branchId: byName.id, created: false };
     }
     // Name not found: offer to create it interactively, mirroring `branch create`.
     if (isCi() || !process.stdout.isTTY) {
@@ -101,34 +110,70 @@ const resolveBranchId = async (props, projectId) => {
     if (!create) {
         throw new Error(`Aborted: branch "${ref}" was not found and not created.`);
     }
-    return createBranch(props, projectId, ref, branches);
+    return {
+        branchId: await createBranch(props, projectId, ref, branches),
+        created: true,
+    };
 };
 const notFoundMessage = (ref, branches) => `Branch ${ref} not found.\nAvailable branches: ${branches
     .map((b) => b.name)
     .join(', ')}`;
-const pickBranchInteractively = async (branches, projectId) => {
+/** 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.');
     }
-    if (branches.length === 0) {
-        throw new Error(`No branches found for project ${projectId}.`);
-    }
-    const defaultIndex = Math.max(0, branches.findIndex((b) => b.default));
-    const { branchId } = await prompts({
+    // 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: 'branchId',
+        name: 'choice',
         message: 'Which branch would you like to check out?',
-        choices: branches.map((b) => ({
-            title: `${b.default ? '✱ ' : ''}${b.name} (${b.id})`,
-            value: b.id,
-        })),
-        initial: defaultIndex,
+        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 (!branchId) {
+    if (choice === undefined) {
         throw new Error('Aborted: no branch selected.');
     }
-    return branchId;
+    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>`:

package/commands/config.js

@@ -0,0 +1,249 @@
+import { resolveConfig } from '@neondatabase/config';
+import { apply, inspect, loadConfigFromFile, plan, } from '@neondatabase/config-runtime';
+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 { bundleEntry } from '../utils/esbuild.js';
+import { zipBundle } from '../utils/zip.js';
+import { writer } from '../writer.js';
+/**
+ * Bundle a function with neonctl's OWN bundler (the shared esbuild helper) so the
+ * config-runtime never has to import esbuild itself. Injecting this keeps esbuild
+ * out of config-runtime's static module graph — and therefore out of the packaged
+ * neonctl snapshot, which resolves esbuild dynamically at deploy time.
+ */
+const neonctlBundler = async (fn) => zipBundle(await bundleEntry(fn.source));
+const INSPECT_FIELDS = ['project', 'branch', 'config'];
+const APPLIED_FIELDS = ['action', 'kind', 'identifier', 'details'];
+const CONFLICT_FIELDS = [
+    'identifier',
+    'field',
+    'current',
+    'desired',
+    'reason',
+];
+/**
+ * Shared `--env` flag for `config plan|apply` and `deploy`. Loads a `.env` into
+ * `process.env` before the policy is evaluated.
+ */
+export const envFlag = {
+    env: {
+        describe: 'Path to a .env file to load into the environment before evaluating neon.ts ' +
+            '(so function env values resolve from it). Existing env vars are not overridden.',
+        type: 'string',
+    },
+};
+/** Apply-only flags, exported so `deploy` can reuse the exact same surface. */
+export const applyFlags = {
+    'update-existing': {
+        describe: 'Auto-confirm overriding existing remote settings on the branch',
+        type: 'boolean',
+        default: false,
+    },
+    'allow-protected': {
+        describe: 'Auto-confirm applying to a branch marked protected on Neon',
+        type: 'boolean',
+        default: false,
+    },
+};
+export const command = 'config';
+export const describe = 'Manage a branch with a neon.ts policy';
+export const builder = (argv) => argv
+    .usage('$0 config <sub-command> [options]')
+    .options({
+    'project-id': {
+        describe: 'Project ID',
+        type: 'string',
+    },
+    branch: {
+        describe: 'Branch ID or name',
+        type: 'string',
+    },
+})
+    .middleware(fillSingleProject)
+    .command('status', "Show the branch's live Neon state", (yargs) => yargs.options({
+    'config-json': {
+        describe: "Print only the branch's live config as neon.ts-shaped JSON " +
+            '(services + branch tuning + preview), to stdout. Useful for ' +
+            'scripting or copying into a neon.ts.',
+        type: 'boolean',
+        default: false,
+    },
+}), (args) => status(args))
+    .command('plan', 'Show what `config apply` would change (dry run)', (yargs) => yargs.options({
+    config: {
+        describe: 'Path to a neon.ts policy (defaults to walking up from cwd)',
+        type: 'string',
+    },
+    ...envFlag,
+}), (args) => planCmd(args))
+    .command('apply', 'Apply a neon.ts policy to the branch', (yargs) => yargs.options({
+    config: {
+        describe: 'Path to a neon.ts policy (defaults to walking up from cwd)',
+        type: 'string',
+    },
+    ...envFlag,
+    ...applyFlags,
+}), (args) => applyCmd(args));
+export const handler = (args) => {
+    return args;
+};
+const loadConfig = async (props) => {
+    // Load the optional --env file FIRST so a `neon.ts` whose function `env` values read
+    // `process.env.X` sees them. Must happen before the policy module is imported/evaluated.
+    if (props.env) {
+        const applied = loadEnvFileIntoProcess(props.env);
+        log.debug('Loaded %d var(s) from %s into the environment: %s', applied.length, props.env, applied.join(', '));
+    }
+    const { config } = await loadConfigFromFile({
+        ...(props.config ? { path: props.config } : {}),
+    });
+    return config;
+};
+export const status = async (props) => {
+    const branchId = await branchIdFromProps(props);
+    const live = await inspect({
+        projectId: props.projectId,
+        branchId,
+        ...(props.apiKey ? { apiKey: props.apiKey } : {}),
+        ...(props.runtimeApi ? { api: props.runtimeApi } : {}),
+    });
+    // The pulled `config` carries the branch's tuning inside a closure that JSON can't
+    // render. Resolve it against the live branch target to get the concrete settings, then
+    // project both that and the separately-pulled preview state into a neon.ts-shaped view.
+    const resolved = resolveConfig(live.config, {
+        name: live.branch.name,
+        id: live.branch.id,
+        exists: true,
+        isDefault: live.branch.isDefault,
+        isProtected: live.branch.protected,
+        ...(live.branch.parent ? { parentId: live.branch.parent } : {}),
+        ...(live.branch.expiresAt ? { expiresAt: live.branch.expiresAt } : {}),
+    });
+    const configView = toNeonConfigView(resolved, live.preview);
+    // `--config-json`: emit just the neon.ts-shaped config to stdout (script-friendly,
+    // copy-paste-able), regardless of the global --output.
+    if (props.configJson) {
+        process.stdout.write(`${JSON.stringify(configView, null, 2)}\n`);
+        return;
+    }
+    // Default: the live project/branch tables, but with the unhelpful raw `config` replaced
+    // by the resolved neon.ts-shaped view so the user sees enabled infra + branch tuning.
+    writer(props).end({ project: live.project, branch: live.branch, config: configView }, { fields: INSPECT_FIELDS });
+};
+export const planCmd = async (props) => {
+    const config = await loadConfig(props);
+    const branchId = await branchIdFromProps(props);
+    // `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, {
+        projectId: props.projectId,
+        branchId,
+        ...(props.apiKey ? { apiKey: props.apiKey } : {}),
+        ...(props.runtimeApi ? { api: props.runtimeApi } : {}),
+    });
+    reportPushResult(props, result, 'plan');
+};
+export const applyCmd = async (props) => {
+    const config = await loadConfig(props);
+    const branchId = await branchIdFromProps(props);
+    const result = await apply(config, {
+        projectId: props.projectId,
+        branchId,
+        ...(props.apiKey ? { apiKey: props.apiKey } : {}),
+        ...(props.runtimeApi ? { api: props.runtimeApi } : {}),
+        ...(props.updateExisting ? { updateExisting: true } : {}),
+        ...(props.allowProtected ? { allowProtectedBranch: true } : {}),
+        bundleFunction: neonctlBundler,
+    });
+    reportPushResult(props, result, 'apply');
+};
+/**
+ * Render a {@link PushResult}. JSON/YAML output emits the raw result verbatim so it
+ * can be piped; the human-readable path renders the actual changes (dropping noops)
+ * and any blocking conflicts as tables, or a "nothing to do" line when both are empty.
+ */
+const reportPushResult = (props, result, mode) => {
+    if (props.output === 'json' || props.output === 'yaml') {
+        writer(props).end(result, { fields: [] });
+        return;
+    }
+    const changes = result.applied
+        .filter((change) => change.action !== 'noop')
+        .map((change) => ({
+        action: change.action,
+        kind: change.kind,
+        identifier: change.identifier,
+        details: change.details ? JSON.stringify(change.details) : '',
+    }));
+    const conflicts = result.conflicts.map((conflict) => ({
+        identifier: conflict.identifier,
+        field: conflict.field,
+        current: stringify(conflict.current),
+        desired: stringify(conflict.desired),
+        reason: conflict.reason,
+    }));
+    if (changes.length === 0 && conflicts.length === 0) {
+        log.info(`No changes — branch ${result.branchName} already matches the policy.`);
+        return;
+    }
+    const out = writer(props);
+    if (changes.length > 0) {
+        out.write(changes, {
+            fields: APPLIED_FIELDS,
+            title: mode === 'plan' ? 'Planned changes' : 'Applied changes',
+        });
+    }
+    if (conflicts.length > 0) {
+        out.write(conflicts, { fields: CONFLICT_FIELDS, title: 'Conflicts' });
+    }
+    out.end();
+    if (conflicts.length > 0) {
+        log.info('Resolve the conflicts above, or re-run with --update-existing to override the current remote settings.');
+    }
+};
+const stringify = (value) => value === undefined
+    ? ''
+    : typeof value === 'string'
+        ? value
+        : JSON.stringify(value);
+/**
+ * Apply a `neon.ts` policy to a **freshly created** branch (used by `neonctl checkout`
+ * when it creates a branch). No-op when there is no `neon.ts` on the path from cwd up to
+ * the repo root — checkout still succeeds, it just has no policy to apply.
+ *
+ * The branch was just created by us, so we apply non-interactively (`updateExisting` /
+ * `allowProtectedBranch`) — there is no pre-existing state a user would be surprised to
+ * see overridden. Functions are bundled with neonctl's own esbuild helper.
+ */
+export const applyPolicyOnCreate = 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;
+        throw err;
+    }
+    log.info('Applying neon.ts policy to the new branch…');
+    const result = await apply(config, {
+        projectId: props.projectId,
+        branchId: props.branchId,
+        ...(props.apiKey ? { apiKey: props.apiKey } : {}),
+        ...(props.runtimeApi ? { api: props.runtimeApi } : {}),
+        updateExisting: true,
+        allowProtectedBranch: true,
+        bundleFunction: neonctlBundler,
+    });
+    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(', '));
+};

package/commands/deploy.js

@@ -0,0 +1,25 @@
+import { fillSingleProject } from '../utils/enrichers.js';
+import { applyCmd, applyFlags, envFlag } from './config.js';
+export const command = 'deploy';
+export const describe = 'Apply a neon.ts policy to a branch (alias for `config apply`)';
+export const builder = (argv) => argv
+    .usage('$0 deploy [options]')
+    .options({
+    'project-id': {
+        describe: 'Project ID',
+        type: 'string',
+    },
+    branch: {
+        describe: 'Branch ID or name',
+        type: 'string',
+    },
+    config: {
+        describe: 'Path to a neon.ts policy (defaults to walking up from cwd)',
+        type: 'string',
+    },
+    ...envFlag,
+    ...applyFlags,
+})
+    .middleware(fillSingleProject)
+    .strict();
+export const handler = (props) => applyCmd(props);