neon 2.41.0 → 2.42.0

package/dist/commands/config.js

@@ -5,7 +5,7 @@ import { apply, createBranch as createBranchFromPolicy, inspect, isPartialBranch
 import chalk from "chalk";
 import { getApiClient } from "../api.js";
 import { toNeonConfigView } from "../config_format.js";
-import { FUNCTION_FILENAME, FUNCTION_SLUG, FUNCTION_TEMPLATE, NEON_SERVICES, NO_SERVICES, parseServices, REQUIRED_PACKAGES, renderNeonConfig, } from "../config_template.js";
+import { FUNCTION_FILENAME, FUNCTION_SLUG, FUNCTION_TEMPLATE, NEON_SERVICES, NO_SERVICES, parseServices, REQUIRED_PACKAGES, renderNeonConfig, renderNeonConfigFromView, } from "../config_template.js";
 import { contextBranch, readContextFile } from "../context.js";
 import { isCi } from "../env.js";
 import { loadEnvFileIntoProcess } from "../env_file.js";
@@ -143,10 +143,39 @@ const scaffoldFunction = (cwd) => {
     writeFileSync(path, FUNCTION_TEMPLATE);
     log.info("Created %s — the source of the %s function.", FUNCTION_FILENAME, FUNCTION_SLUG);
 };
+/**
+ * Read a branch's live state and render it as a `neon.ts`. The read goes through the same
+ * {@link liveConfigView} as `config status`, so a seeded policy declares exactly what
+ * `config status --config-json` reports — including what it cannot report (see
+ * {@link renderNeonConfigFromView}).
+ */
+const seedFromBranch = async (props) => {
+    const { apiClient, projectId } = props;
+    if (!apiClient || !projectId) {
+        throw new Error("--from-branch needs a project. Pass --project-id, or run `neon link` to pin one in .neon.");
+    }
+    const ref = await resolveBranchRef({
+        apiClient,
+        projectId,
+        ...(props.branch !== undefined ? { branch: props.branch } : {}),
+    });
+    if (ref.usedDefault) {
+        log.info("No branch pinned or passed — seeding from the project's default branch %s.", ref.branchName);
+    }
+    const { live, view } = await liveConfigView({
+        projectId,
+        branchId: ref.branchId,
+        ...(props.apiKey ? { apiKey: props.apiKey } : {}),
+        ...(props.apiHost ? { apiHost: props.apiHost } : {}),
+        ...(props.runtimeApi ? { runtimeApi: props.runtimeApi } : {}),
+    });
+    const rendered = renderNeonConfigFromView(view, live.branch.name);
+    return { ...rendered, branchName: live.branch.name };
+};
 /**
  * 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}).
+ * Local-only unless `--from-branch` is set (see {@link isConfigInit}).
  */
 export const initCmd = async (props) => {
     const cwd = props.cwd ?? process.cwd();
@@ -158,6 +187,16 @@ export const initCmd = async (props) => {
     if (existing) {
         log.info("Found an existing %s — leaving it untouched.", existing);
     }
+    else if (props.fromBranch) {
+        const { source, seeded, branchName } = await seedFromBranch(props);
+        writeFileSync(join(cwd, "neon.ts"), source);
+        if (seeded) {
+            log.info("Created neon.ts from the live state of %s.", branchName);
+        }
+        else {
+            log.info("%s declares no services and no branch settings — created neon.ts with the starter policy instead.", branchName);
+        }
+    }
     else {
         const services = await resolveServices(props);
         writeFileSync(join(cwd, "neon.ts"), renderNeonConfig(services));
@@ -251,10 +290,47 @@ export const builder = (argv) => argv
             "terminal, starter policy in CI or without a TTY.",
         type: "string",
     },
+    "from-branch": {
+        describe: "Seed neon.ts from a branch's live Neon state instead of asking. Uses the " +
+            "branch pinned in .neon, or --branch <name|id>, or the project's default " +
+            "branch. The only mode of `config init` that calls the Neon API.",
+        type: "boolean",
+        // No `default`: yargs counts a defaulted key as provided, so
+        // `default: false` makes `conflicts` reject every `--services` run.
+        conflicts: "services",
+    },
 }), (args) => initCmd(args));
 export const handler = (args) => {
     return args;
 };
+/**
+ * A branch's live state, plus that state projected into the `neon.ts`-shaped
+ * {@link NeonConfigView}. Shared by `config status` and `config init --from-branch` so both
+ * read the branch through one path: what `status --config-json` prints is exactly what
+ * `init --from-branch` writes.
+ *
+ * The pulled `config` carries the branch's tuning inside a closure that JSON can't render, so
+ * it is resolved against the live branch target first.
+ */
+const liveConfigView = async (opts) => {
+    const live = await inspect({
+        projectId: opts.projectId,
+        branchId: opts.branchId,
+        ...(opts.apiKey ? { apiKey: opts.apiKey } : {}),
+        ...(opts.apiHost ? { apiHost: opts.apiHost } : {}),
+        ...(opts.runtimeApi ? { api: opts.runtimeApi } : {}),
+    });
+    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 } : {}),
+    });
+    return { live, view: toNeonConfigView(resolved, live.preview) };
+};
 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.
@@ -289,27 +365,13 @@ export const status = async (props) => {
     if (!props.configJson) {
         announceTargetBranch(props, branch, "Inspecting branch");
     }
-    const branchId = branch.branchId;
-    const live = await inspect({
+    const { live, view: configView } = await liveConfigView({
         projectId: props.projectId,
-        branchId,
+        branchId: branch.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 } : {}),
+        ...(props.runtimeApi ? { runtimeApi: props.runtimeApi } : {}),
     });
-    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) {

package/dist/config_template.js

@@ -60,22 +60,43 @@ export const parseServices = (raw) => {
     }
     return NEON_SERVICES.filter((service) => names.includes(service));
 };
+/**
+ * One indentation level in the emitted `neon.ts`. Two spaces, which is what every renderer
+ * here produces and what `config_template.format.test.ts` holds them to.
+ */
+const INDENT = "  ";
+/**
+ * Prefix each line with `level` indentation levels. Nesting is expressed as a number at the
+ * one place that knows the structure, rather than as literal spaces at every push site — a
+ * miscounted space is otherwise invisible in review and only shows up in a user's file.
+ */
+const at = (level, ...lines) => lines.map((line) => INDENT.repeat(level) + line);
+/** Wrap `body` in an object-literal block named `key`, indented from `level`. */
+const block = (level, key, body) => [
+    ...at(level, `${key}: {`),
+    ...body,
+    ...at(level, "},"),
+];
 /** The `preview` block for the selected services, or "" when none of them is a preview feature. */
 const renderPreview = (services) => {
     const lines = [];
     if (services.includes("ai-gateway")) {
-        lines.push("    aiGateway: true,");
+        lines.push(...at(2, "aiGateway: true,"));
     }
     if (services.includes("functions")) {
-        lines.push("    functions: {", `      ${FUNCTION_SLUG}: { name: "${FUNCTION_NAME}", source: "./${FUNCTION_FILENAME}" },`, "    },");
+        lines.push(...block(2, "functions", [
+            ...at(3, `${FUNCTION_SLUG}: { name: "${FUNCTION_NAME}", source: "./${FUNCTION_FILENAME}" },`),
+        ]));
     }
     if (services.includes("storage")) {
-        lines.push("    buckets: {", `      // "private" is the default; use "public_read" for anonymous reads`, `      ${BUCKET_NAME}: { access: "private" },`, "    },");
+        lines.push(...block(2, "buckets", [
+            ...at(3, `// "private" is the default; use "public_read" for anonymous reads`, `${BUCKET_NAME}: { access: "private" },`),
+        ]));
     }
     if (lines.length === 0) {
         return "";
     }
-    return `${["  preview: {", ...lines, "  },"].join("\n")}\n`;
+    return `${block(1, "preview", lines).join("\n")}\n`;
 };
 /**
  * Render the `neon.ts` policy `config init` writes. With no services this is the starter
@@ -104,6 +125,107 @@ ${renderPreview(services)}  // Branch policy: per-branch tuning
   },
 });
 `;
+/** Render a scalar the way it has to appear in TypeScript source. */
+const renderScalar = (value) => typeof value === "string" ? `"${value}"` : String(value);
+/**
+ * Render an object key. Live names are not identifiers: a Neon bucket may be called
+ * `smoke-uploads`, which as a bare key is a subtraction and a syntax error. Anything that
+ * isn't a plain identifier gets quoted.
+ */
+const renderKey = (name) => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
+/**
+ * The `branch` closure for a policy seeded from live state, or "" when the branch carries no
+ * tuning worth declaring.
+ *
+ * `protected` is read but never declared: it is a fact about one branch, while a policy
+ * `protected` applies to every branch the policy runs against. It becomes a comment instead.
+ */
+const renderSeededBranch = (view) => {
+    const settings = [];
+    if (view.branch?.parent !== undefined) {
+        settings.push(...at(2, `parent: ${renderScalar(view.branch.parent)},`));
+    }
+    if (view.branch?.ttl !== undefined) {
+        settings.push(...at(2, `ttl: ${renderScalar(view.branch.ttl)},`));
+    }
+    const compute = view.branch?.postgres?.computeSettings;
+    const computeFields = Object.entries(compute ?? {}).filter(([, value]) => value !== undefined);
+    if (computeFields.length > 0) {
+        settings.push(...block(2, "postgres", [
+            ...block(3, "computeSettings", computeFields.flatMap(([field, value]) => at(4, `${field}: ${renderScalar(value)},`))),
+        ]));
+    }
+    if (settings.length === 0) {
+        return "";
+    }
+    // An arrow returning an object literal, so the closing line is `}),` rather than `},`.
+    return `${[...at(1, "branch: () => ({"), ...settings, ...at(1, "}),")].join("\n")}\n`;
+};
+/** The `preview` block for a policy seeded from live state. */
+const renderSeededPreview = (view, branchName) => {
+    const lines = [];
+    const buckets = Object.entries(view.preview?.buckets ?? {});
+    if (buckets.length > 0) {
+        lines.push(...block(2, "buckets", buckets.flatMap(([name, bucket]) => at(3, `${renderKey(name)}: { access: "${bucket.access}" },`))));
+    }
+    // A deployed function cannot be declared from live state: `source` is a path in the
+    // user's project and the branch only knows the uploaded bundle. Listing the slugs as a
+    // commented-out block is the most a read-back can honestly produce.
+    const functions = Object.entries(view.preview?.functions ?? {});
+    if (functions.length > 0) {
+        lines.push(...at(2, `// ${branchName} has ${functions.length} deployed function${functions.length === 1 ? "" : "s"}.`, "// Declaring one needs the local source path, which the branch does not know:", "// functions: {", ...functions.map(([slug, fn]) => `//   ${renderKey(slug)}: { name: "${fn.name}", source: "./${slug}.ts" },`), "// },"));
+    }
+    if (lines.length === 0) {
+        return "";
+    }
+    return `${block(1, "preview", lines).join("\n")}\n`;
+};
+/**
+ * Render a `neon.ts` from a branch's live state (`config init --from-branch`).
+ *
+ * Only what the branch can actually report is declared. Three things are deliberately
+ * absent, each for its own reason:
+ *
+ * - **The AI Gateway** has no branch-level enabled state to read — it is always available and
+ *   credential-gated — so `pullConfig` cannot tell whether a policy would enable it.
+ * - **Functions** cannot round-trip (no `source` path on the remote); they are listed as a
+ *   commented-out block.
+ * - **`protected`** is branch state rather than policy intent, so it is reported as a comment.
+ *
+ * A branch with nothing to report (no services, no tuning) renders the starter policy rather
+ * than an empty `defineConfig({})`: seeding found nothing, and the caller says so.
+ */
+export const renderNeonConfigFromView = (view, branchName) => {
+    const services = [
+        view.auth ? "  auth: true," : "",
+        view.dataApi ? "  dataApi: true," : "",
+    ].filter((line) => line !== "");
+    const preview = renderSeededPreview(view, branchName);
+    const branch = renderSeededBranch(view);
+    if (services.length === 0 && preview === "" && branch === "") {
+        return { source: renderNeonConfig([]), seeded: false };
+    }
+    const protectedNote = view.branch?.protected
+        ? `// ${branchName} is protected on Neon. Not declared here: a policy \`protected\` would\n// apply to every branch this policy is applied to.\n`
+        : "";
+    const body = [
+        ...services,
+        ...(preview === "" ? [] : [preview.trimEnd()]),
+        ...(branch === "" ? [] : [branch.trimEnd()]),
+    ].join("\n");
+    return {
+        source: `import { defineConfig } from "${CONFIG_PACKAGE}/v1";
+
+// Seeded by \`neon config init --from-branch\` from ${branchName}.
+// The AI Gateway is not readable from a branch (always available, credential-gated), so add
+// \`preview: { aiGateway: true }\` if the policy should declare it.
+${protectedNote}export default defineConfig({
+${body}
+});
+`,
+        seeded: true,
+    };
+};
 /**
  * The handler written alongside `neon.ts` when `functions` is selected. It has to exist:
  * `FunctionDef.source` is only resolved when `config apply` / `deploy` bundles it, so a

package/dist/context.js

@@ -29,8 +29,17 @@ export const isCurrentBranchProbe = (args) => args.currentBranch === true &&
  * never calls the Neon API. Gated on the exact command path so the global auth
  * middleware and the single-project resolver can skip it (it runs with no API
  * client), mirroring {@link isCurrentBranchProbe}.
+ *
+ * `--from-branch` is the exception: it seeds the policy from a branch's live state, so it
+ * needs both credentials and a resolved project. The raw argv is checked alongside the parsed
+ * flag because this runs from middleware that executes before validation, where the parsed
+ * value may not be populated yet (the same reason `analytics.ts` scans argv for
+ * `--current-branch`).
  */
-export const isConfigInit = (args) => args._[0] === "config" && args._[1] === "init";
+export const isConfigInit = (args) => args._[0] === "config" &&
+    args._[1] === "init" &&
+    args.fromBranch !== true &&
+    !process.argv.includes("--from-branch");
 /**
  * `neon profile …` manages credentials on disk and never calls the Neon API, so the global
  * auth middleware must skip it — mirroring {@link isConfigInit}.

package/dist/utils/enrichers.js

@@ -42,9 +42,7 @@ export const branchIdFromProps = async (props) => {
     return props.branchId;
 };
 export const resolveBranchRef = async (props) => {
-    const branch = "branch" in props && typeof props.branch === "string"
-        ? props.branch
-        : props.id;
+    const branch = typeof props.branch === "string" ? props.branch : props.id;
     const { data } = await props.apiClient.listProjectBranches({
         projectId: props.projectId,
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neon",
-  "version": "2.41.0",
+  "version": "2.42.0",
   "description": "CLI tool for Neon, the cloud backend primitives built around Lakebase Postgres",
   "keywords": [
     "neon",
@@ -55,11 +55,11 @@
     "which": "3.0.1",
     "yaml": "^2.9.0",
     "yargs": "17.7.2",
-    "@neon/config": "0.13.0",
-    "@neon/sdk": "1.4.0",
-    "@neon/config-runtime": "0.12.1",
-    "neon-init": "0.20.6",
-    "@neon/env": "0.13.1"
+    "@neon/sdk": "1.4.1",
+    "@neon/config": "0.13.1",
+    "@neon/config-runtime": "0.12.2",
+    "@neon/env": "0.13.2",
+    "neon-init": "0.20.6"
   },
   "optionalDependencies": {
     "esbuild": "0.28.1"