neonctl 2.28.0 → 2.29.0

package/dist/commands/config.js

@@ -1,17 +1,20 @@
-import chalk from 'chalk';
-import { resolveConfig } from '@neondatabase/config';
-import { apply, createBranch as createBranchFromPolicy, inspect, loadConfigFromFile, plan, } from '@neondatabase/config-runtime';
-import { toNeonConfigView } from '../config_format.js';
-import { contextBranch, readContextFile } from '../context.js';
-import { log } from '../log.js';
-import { isCi } from '../env.js';
-import { loadEnvFileIntoProcess } from '../env_file.js';
-import { fillSingleProject, resolveBranchRef } from '../utils/enrichers.js';
-import { announceTargetBranch } from '../utils/branch_notice.js';
-import { bundleEntry } from '../utils/esbuild.js';
-import { zipBundle } from '../utils/zip.js';
-import { writer } from '../writer.js';
-import { autoPullEnvAfterPin } from './env.js';
+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
@@ -19,19 +22,19 @@ import { autoPullEnvAfterPin } from './env.js';
  * 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 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 APPLIED_FIELDS = ["action", "kind", "identifier"];
 const CONFLICT_FIELDS = [
-    'identifier',
-    'field',
-    'current',
-    'desired',
-    'reason',
+    "identifier",
+    "field",
+    "current",
+    "desired",
+    "reason",
 ];
 /**
  * Shared `--env` flag for `config plan|apply` and `deploy`. Loads a `.env` into
@@ -39,21 +42,21 @@ const CONFLICT_FIELDS = [
  */
 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',
+        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',
+    "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',
+    "allow-protected": {
+        describe: "Auto-confirm applying to a branch marked protected on Neon",
+        type: "boolean",
         default: false,
     },
 };
@@ -63,60 +66,181 @@ export const applyFlags = {
  * same bundled convenience as `link` / `checkout`. On by default; `--no-env-pull` opts out.
  */
 export const envPullFlag = {
-    'env-pull': {
+    "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',
+            "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,
     },
 };
-export const command = 'config';
-export const describe = 'Manage a branch with a neon.ts policy';
+// ── `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]')
+    .usage("$0 config <sub-command> [options]")
     .options({
-    'project-id': {
-        describe: 'Project ID',
-        type: 'string',
+    "project-id": {
+        describe: "Project ID",
+        type: "string",
     },
     branch: {
-        describe: 'Branch ID or name',
-        type: 'string',
+        describe: "Branch ID or name",
+        type: "string",
     },
 })
     .middleware(fillSingleProject)
-    .command('status', "Show the branch's live Neon state", (yargs) => yargs.options({
-    'config-json': {
+    .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',
+            "(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',
+    "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({
+    .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',
+        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({
+    .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',
+        describe: "Path to a neon.ts policy (defaults to walking up from cwd)",
+        type: "string",
     },
     ...envFlag,
     ...applyFlags,
     ...envPullFlag,
-}), (args) => applyCmd(args));
+}), (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;
 };
@@ -125,7 +249,7 @@ const loadConfig = async (props) => {
     // `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(', '));
+        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 } : {}),
@@ -143,7 +267,7 @@ export const status = async (props) => {
         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.');
+            log.info("No branch pinned. Run `neonctl checkout <branch>` to pin a branch and pull its env vars.");
             process.exitCode = 1;
         }
         return;
@@ -152,7 +276,7 @@ export const status = async (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');
+        announceTargetBranch(props, branch, "Inspecting branch");
     }
     const branchId = branch.branchId;
     const live = await inspect({
@@ -188,7 +312,7 @@ export const status = async (props) => {
 export const planCmd = async (props) => {
     const config = await loadConfig(props);
     const branch = await resolveBranchRef(props);
-    announceTargetBranch(props, branch, 'Planning against branch');
+    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).
@@ -199,12 +323,12 @@ export const planCmd = async (props) => {
         ...(props.apiHost ? { apiHost: props.apiHost } : {}),
         ...(props.runtimeApi ? { api: props.runtimeApi } : {}),
     });
-    reportPushResult(props, result, 'plan', utilizedServices(config));
+    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');
+    announceTargetBranch(props, branch, "Applying to branch");
     const branchId = branch.branchId;
     const result = await apply(config, {
         projectId: props.projectId,
@@ -216,7 +340,7 @@ export const applyCmd = async (props) => {
         ...(props.allowProtected ? { allowProtectedBranch: true } : {}),
         bundleFunction: neonctlBundler,
     });
-    reportPushResult(props, result, 'apply', utilizedServices(config));
+    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
@@ -232,7 +356,7 @@ export const applyCmd = async (props) => {
 const isToggleEnabled = (toggle) => {
     if (toggle === undefined)
         return false;
-    if (typeof toggle === 'boolean')
+    if (typeof toggle === "boolean")
         return toggle;
     return toggle.enabled !== false;
 };
@@ -246,19 +370,19 @@ const isToggleEnabled = (toggle) => {
  * lives in the per-branch closure), so reading it straight off `config` is accurate.
  */
 const utilizedServices = (config) => {
-    const services = ['Postgres'];
+    const services = ["Postgres"];
     if (isToggleEnabled(config.auth))
-        services.push('Neon Auth');
+        services.push("Neon Auth");
     if (isToggleEnabled(config.dataApi))
-        services.push('Data API');
+        services.push("Data API");
     if (Object.keys(config.preview?.buckets ?? {}).length > 0) {
-        services.push('Object Storage');
+        services.push("Object Storage");
     }
     if (Object.keys(config.preview?.functions ?? {}).length > 0) {
-        services.push('Functions');
+        services.push("Functions");
     }
     if (isToggleEnabled(config.preview?.aiGateway))
-        services.push('AI Gateway');
+        services.push("AI Gateway");
     return services;
 };
 /**
@@ -270,12 +394,12 @@ const utilizedServices = (config) => {
  * for being missing from the plan above.
  */
 const reportPushResult = (props, result, mode, services) => {
-    if (props.output === 'json' || props.output === 'yaml') {
+    if (props.output === "json" || props.output === "yaml") {
         writer(props).end({ ...result, services }, { fields: [] });
         return;
     }
     const changes = result.applied
-        .filter((change) => change.action !== 'noop')
+        .filter((change) => change.action !== "noop")
         .map((change) => ({
         action: change.action,
         kind: change.kind,
@@ -293,11 +417,11 @@ const reportPushResult = (props, result, mode, services) => {
     // Keyed by slug so a function never shows twice.
     const functionUrlBySlug = new Map();
     for (const change of result.applied) {
-        if (change.action === 'noop')
+        if (change.action === "noop")
             continue;
         const slug = change.details?.slug;
         const invocationUrl = change.details?.invocationUrl;
-        if (typeof slug === 'string' && typeof invocationUrl === 'string') {
+        if (typeof slug === "string" && typeof invocationUrl === "string") {
             functionUrlBySlug.set(slug, invocationUrl);
         }
     }
@@ -306,11 +430,11 @@ const reportPushResult = (props, result, mode, services) => {
     if (changes.length > 0) {
         out.write(changes, {
             fields: APPLIED_FIELDS,
-            title: mode === 'plan' ? 'Planned changes' : 'Applied changes',
+            title: mode === "plan" ? "Planned changes" : "Applied changes",
         });
     }
     if (conflicts.length > 0) {
-        out.write(conflicts, { fields: CONFLICT_FIELDS, title: 'Conflicts' });
+        out.write(conflicts, { fields: CONFLICT_FIELDS, title: "Conflicts" });
     }
     // Flush any tables, then append the lists/summary so they read directly below them.
     out.end();
@@ -318,7 +442,7 @@ const reportPushResult = (props, result, mode, services) => {
     // 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';
+        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`);
@@ -327,14 +451,14 @@ const reportPushResult = (props, result, mode, services) => {
     if (noChanges) {
         log.info(`No changes — branch ${result.branchName} already matches the policy.`);
     }
-    out.text(`\nUtilized services: ${services.join(', ')}\n`);
+    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.');
+        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'
+    ? ""
+    : typeof value === "string"
         ? value
         : JSON.stringify(value);
 /**
@@ -359,7 +483,7 @@ export const applyPolicyOnCreate = async (props) => {
             return;
         throw err;
     }
-    log.info('Applying neon.ts policy to the new branch…');
+    log.info("Applying neon.ts policy to the new branch…");
     const result = await apply(config, {
         projectId: props.projectId,
         branchId: props.branchId,
@@ -374,12 +498,12 @@ export const applyPolicyOnCreate = async (props) => {
 };
 /** 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');
+    const changes = result.applied.filter((c) => c.action !== "noop");
     if (changes.length === 0) {
-        log.info('neon.ts applied — no changes were needed.');
+        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("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
@@ -414,7 +538,7 @@ export const createBranchFromPolicyOnCheckout = async (props) => {
         ...(props.runtimeApi ? { api: props.runtimeApi } : {}),
         bundleFunction: neonctlBundler,
     });
-    log.info('Created branch %s (%s) from neon.ts policy.', branchName, branchId);
+    log.info("Created branch %s (%s) from neon.ts policy.", branchName, branchId);
     logPolicyResult(result);
     return { branchId };
 };