neon 2.1.2 → 2.29.1

package/dist/commands/config.js

@@ -0,0 +1,544 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { resolveConfig } from "@neon/config";
+import { apply, createBranch as createBranchFromPolicy, inspect, loadConfigFromFile, plan, } from "@neon/config-runtime";
+import chalk from "chalk";
+import { toNeonConfigView } from "../config_format.js";
+import { contextBranch, readContextFile } from "../context.js";
+import { isCi } from "../env.js";
+import { loadEnvFileIntoProcess } from "../env_file.js";
+import { log } from "../log.js";
+import { announceTargetBranch } from "../utils/branch_notice.js";
+import { fillSingleProject, resolveBranchRef } from "../utils/enrichers.js";
+import { bundleEntry } from "../utils/esbuild.js";
+import { addDependenciesArgs, resolvePackageManager, runCommand, } from "../utils/package_manager.js";
+import { zipBundle } from "../utils/zip.js";
+import { writer } from "../writer.js";
+import { autoPullEnvAfterPin } from "./env.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"];
+// Deliberately minimal: action/kind/identifier are short and fixed-ish, so the table can
+// never overflow. Per-change `details` (a function's long invocationUrl in particular) are
+// intentionally NOT a column — they used to be JSON-stringified into a cell and blew the
+// table past 190 cols. Function URLs are printed below as a plain list (see reportPushResult),
+// and the full details are still available via `--output json`.
+const APPLIED_FIELDS = ["action", "kind", "identifier"];
+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,
+    },
+};
+/**
+ * `--env-pull` for `config apply` / `deploy` (shared so both expose the identical surface).
+ * After a successful apply, the branch's Neon env vars are written to a local `.env` — the
+ * same bundled convenience as `link` / `checkout`. On by default; `--no-env-pull` opts out.
+ */
+export const envPullFlag = {
+    "env-pull": {
+        describe: "Pull the branch's Neon env vars (DATABASE_URL, …) into a local .env after a " +
+            "successful apply. 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,
+    },
+};
+// ── `config init` ─────────────────────────────────────────────────────────────
+/**
+ * The published npm packages a `neon.ts` project needs — the `@neon/*` org names.
+ *
+ * ⚠️ These ship to users the next time `neonctl` is released, so do NOT release
+ * neonctl until `@neon/config` and `@neon/env` are published to npm — otherwise
+ * `config init` would install packages that don't exist yet. (The libraries are
+ * mid-migration from `@neondatabase/*`; track their publish before cutting a CLI
+ * release.)
+ */
+const CONFIG_PACKAGE = "@neon/config";
+const ENV_PACKAGE = "@neon/env";
+const REQUIRED_PACKAGES = [CONFIG_PACKAGE, ENV_PACKAGE];
+/** package.json fields a dependency can be declared in. */
+const DEPENDENCY_FIELDS = [
+    "dependencies",
+    "devDependencies",
+    "peerDependencies",
+    "optionalDependencies",
+];
+/** Config filenames the runtime loads (mirrors @neon/config's loader). */
+const NEON_CONFIG_FILENAMES = ["neon.ts", "neon.mts", "neon.js", "neon.mjs"];
+/** Whether `dir` already has a Neon config file the runtime would load. */
+export const hasNeonConfigFile = (dir) => NEON_CONFIG_FILENAMES.some((name) => existsSync(join(dir, name)));
+/** Starter `neon.ts` written by `config init` when a project has none. */
+const NEON_CONFIG_TEMPLATE = `import { defineConfig } from "${CONFIG_PACKAGE}/v1";
+
+export default defineConfig({
+  // Declare your Neon services here
+  auth: false,
+  // Branch policy: per-branch tuning
+  branch: (branch) => {
+    if (branch.isDefault) {
+      // Default branch: no overrides, uses project defaults
+      return {};
+    }
+    if (!branch.exists) {
+      // New non-default branches: auto-expire
+      // Run \`neon checkout <name>\` to create a new branch with these settings
+      return { ttl: "7d" };
+    }
+    // Existing branch: no changes
+    return {};
+  },
+});
+`;
+const isRecord = (value) => typeof value === "object" && value !== null;
+/**
+ * The {@link REQUIRED_PACKAGES} not already declared in the project's package.json
+ * (any dependency field). A missing or malformed package.json means none are
+ * declared, so all are reported missing.
+ */
+const missingDependencies = (cwd) => {
+    const declared = new Set();
+    const pkgPath = join(cwd, "package.json");
+    if (existsSync(pkgPath)) {
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(pkgPath, "utf8"));
+        }
+        catch {
+            parsed = undefined;
+        }
+        if (isRecord(parsed)) {
+            for (const field of DEPENDENCY_FIELDS) {
+                const deps = parsed[field];
+                if (isRecord(deps)) {
+                    for (const name of Object.keys(deps))
+                        declared.add(name);
+                }
+            }
+        }
+    }
+    return REQUIRED_PACKAGES.filter((pkg) => !declared.has(pkg));
+};
+/**
+ * Scaffold a `neon.ts` policy and make sure the Neon config packages are
+ * installed, so a project can go straight to `neon config plan` / `apply`.
+ * Purely local — it never touches the Neon API (see {@link isConfigInit}).
+ */
+export const initCmd = async (props) => {
+    const cwd = props.cwd ?? process.cwd();
+    const run = props.run ?? runCommand;
+    // 1. Scaffold neon.ts unless the project already has a Neon config file.
+    const existing = NEON_CONFIG_FILENAMES.find((name) => existsSync(join(cwd, name)));
+    if (existing) {
+        log.info("Found an existing %s — leaving it untouched.", existing);
+    }
+    else {
+        writeFileSync(join(cwd, "neon.ts"), NEON_CONFIG_TEMPLATE);
+        log.info("Created neon.ts with a starter policy.");
+    }
+    // 2. Make sure the config packages are installed.
+    const missing = missingDependencies(cwd);
+    if (missing.length === 0) {
+        log.info("%s are already installed.", REQUIRED_PACKAGES.join(" and "));
+    }
+    else {
+        const pm = resolvePackageManager();
+        const args = addDependenciesArgs(pm, missing);
+        if (props.install === false) {
+            log.info("Install the Neon config packages to use neon.ts: %s %s", pm, args.join(" "));
+        }
+        else {
+            log.info("Installing %s with %s…", missing.join(", "), pm);
+            const ok = await run(pm, args, cwd);
+            if (!ok) {
+                log.warning("Could not install the config packages automatically. Run by hand: %s %s", pm, args.join(" "));
+            }
+        }
+    }
+    log.info("Next: edit neon.ts, then run `neon config plan` to preview and `neon config apply`.");
+};
+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,
+    },
+    "current-branch": {
+        describe: "Print only the linked branch name from the local .neon file " +
+            "(no network). Exits non-zero when no branch is pinned.",
+        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,
+    ...envPullFlag,
+}), (args) => applyCmd(args))
+    .command("init", "Scaffold a neon.ts policy and install the Neon config packages", (yargs) => yargs.options({
+    install: {
+        describe: "Install @neon/config and @neon/env if they're missing. " +
+            "On by default; use --no-install to just print the command.",
+        type: "boolean",
+        default: true,
+    },
+}), (args) => initCmd(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) => {
+    // `--current-branch` short-circuits here (before resolveBranchRef), so it wins
+    // over --config-json and ignores --output. See ConfigProps.currentBranch / isCurrentBranchProbe.
+    if (props.currentBranch) {
+        const branch = contextBranch(readContextFile(props.contextFile));
+        if (branch) {
+            process.stdout.write(`${branch}\n`);
+        }
+        else {
+            // No branch pinned: hint on stderr and exit non-zero (grep-style) so a prompt's
+            // `when` hides the segment cleanly instead of rendering a bare icon.
+            log.info("No branch pinned. Run `neonctl checkout <branch>` to pin a branch and pull its env vars.");
+            process.exitCode = 1;
+        }
+        return;
+    }
+    const branch = await resolveBranchRef(props);
+    // `--config-json` is a script-friendly mode that emits only JSON to stdout, so keep it
+    // pristine; the regular human view gets the "which branch am I inspecting" guardrail.
+    if (!props.configJson) {
+        announceTargetBranch(props, branch, "Inspecting branch");
+    }
+    const branchId = branch.branchId;
+    const live = await inspect({
+        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
+    // 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 branch = await resolveBranchRef(props);
+    announceTargetBranch(props, branch, "Planning against branch");
+    const branchId = branch.branchId;
+    // `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.apiHost ? { apiHost: props.apiHost } : {}),
+        ...(props.runtimeApi ? { api: props.runtimeApi } : {}),
+    });
+    reportPushResult(props, result, "plan", utilizedServices(config));
+};
+export const applyCmd = async (props) => {
+    const config = await loadConfig(props);
+    const branch = await resolveBranchRef(props);
+    announceTargetBranch(props, branch, "Applying to branch");
+    const branchId = branch.branchId;
+    const result = await apply(config, {
+        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 } : {}),
+        bundleFunction: neonctlBundler,
+    });
+    reportPushResult(props, result, "apply", utilizedServices(config));
+    // After a successful apply/deploy, write the branch's Neon env vars to a local .env —
+    // the same bundled convenience as `link` / `checkout`, so the branch is immediately
+    // usable for local dev. `--no-env-pull` opts out; a pull failure degrades to a warning
+    // (the apply already succeeded). See autoPullEnvAfterPin.
+    await autoPullEnvAfterPin({ ...props, envPull: props.envPull !== false });
+};
+/**
+ * A static service toggle (`auth` / `dataApi` / `preview.aiGateway`) is "on" unless
+ * explicitly disabled: `true` / `{}` / `{ enabled: true }` enable it; `false` /
+ * `{ enabled: false }` / absent leave it off. Mirrors the runtime's `isServiceEnabled`
+ * (which isn't exported), kept tiny and pure so it can be read straight off the policy.
+ */
+const isToggleEnabled = (toggle) => {
+    if (toggle === undefined)
+        return false;
+    if (typeof toggle === "boolean")
+        return toggle;
+    return toggle.enabled !== false;
+};
+/**
+ * Human-readable list of the services a `neon.ts` policy utilizes on the branch, shown under
+ * the plan/apply table. Postgres is always present (every branch has it); the rest are listed
+ * only when the policy declares them. This deliberately surfaces services that produce **no**
+ * plan step — notably the AI Gateway, which is always available and only needs a scoped branch
+ * credential (not a provisioning step) — so adding `preview.aiGateway` to a neon.ts isn't
+ * mistaken for being silently dropped. Service enablement is static top-level config (it never
+ * lives in the per-branch closure), so reading it straight off `config` is accurate.
+ */
+const utilizedServices = (config) => {
+    const services = ["Postgres"];
+    if (isToggleEnabled(config.auth))
+        services.push("Neon Auth");
+    if (isToggleEnabled(config.dataApi))
+        services.push("Data API");
+    if (Object.keys(config.preview?.buckets ?? {}).length > 0) {
+        services.push("Object Storage");
+    }
+    if (Object.keys(config.preview?.functions ?? {}).length > 0) {
+        services.push("Functions");
+    }
+    if (isToggleEnabled(config.preview?.aiGateway))
+        services.push("AI Gateway");
+    return services;
+};
+/**
+ * Render a {@link PushResult}. JSON/YAML output emits the raw result (plus a `services`
+ * summary) 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 — and always closes with the list of services the policy utilizes so a service
+ * that produces no plan step (Postgres, or the credential-gated AI Gateway) isn't mistaken
+ * for being missing from the plan above.
+ */
+const reportPushResult = (props, result, mode, services) => {
+    if (props.output === "json" || props.output === "yaml") {
+        writer(props).end({ ...result, services }, { fields: [] });
+        return;
+    }
+    const changes = result.applied
+        .filter((change) => change.action !== "noop")
+        .map((change) => ({
+        action: change.action,
+        kind: change.kind,
+        identifier: change.identifier,
+    }));
+    const conflicts = result.conflicts.map((conflict) => ({
+        identifier: conflict.identifier,
+        field: conflict.field,
+        current: stringify(conflict.current),
+        desired: stringify(conflict.desired),
+        reason: conflict.reason,
+    }));
+    // Deployed functions carry their invocation URL in the change details — collect them so
+    // we can list where to call each function without digging through the raw details blob.
+    // Keyed by slug so a function never shows twice.
+    const functionUrlBySlug = new Map();
+    for (const change of result.applied) {
+        if (change.action === "noop")
+            continue;
+        const slug = change.details?.slug;
+        const invocationUrl = change.details?.invocationUrl;
+        if (typeof slug === "string" && typeof invocationUrl === "string") {
+            functionUrlBySlug.set(slug, invocationUrl);
+        }
+    }
+    const out = writer(props);
+    const noChanges = changes.length === 0 && conflicts.length === 0;
+    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" });
+    }
+    // Flush any tables, then append the lists/summary so they read directly below them.
+    out.end();
+    // Function URLs are a plain list rather than a table: an invocation URL can be 70+ chars,
+    // which makes any bordered table overflow and wrap awkwardly in a normal terminal. A list
+    // lets each URL reflow on its own line, and stays copy-pasteable.
+    if (functionUrlBySlug.size > 0) {
+        const heading = mode === "plan" ? "Function URLs (after apply)" : "Function URLs";
+        out.text(`\n${isCi() ? heading : chalk.bold(heading)}\n`);
+        for (const [slug, invocationUrl] of functionUrlBySlug) {
+            out.text(`  • ${slug}: ${invocationUrl}\n`);
+        }
+    }
+    if (noChanges) {
+        log.info(`No changes — branch ${result.branchName} already matches the policy.`);
+    }
+    out.text(`\nUtilized services: ${services.join(", ")}\n`);
+    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.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.");
+        return;
+    }
+    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 };
+};