neonctl 2.23.1 → 2.24.1

package/commands/checkout.js

@@ -1,12 +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 { autoPullEnvAfterPin } from './env.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.
@@ -23,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([
     [
@@ -44,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 = 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 +64,56 @@ 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 } : {}),
+        });
+    }
+    // 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,
+    });
 };
-/**
- * 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, {
+            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 };
+        }
+        // The user chose "create a new branch" from the picker.
+        return {
+            branchId: await createBranch(props.apiClient, 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,54 +129,14 @@ 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.apiClient, 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) => {
-    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({
-        type: 'select',
-        name: 'branchId',
-        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,
-    });
-    if (!branchId) {
-        throw new Error('Aborted: no branch selected.');
-    }
-    return branchId;
-};
-/**
- * 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

@@ -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);