@neondatabase/config-runtime 0.0.0 → 0.2.0

package/LICENSE.md

@@ -0,0 +1,178 @@
+# Apache License 2.0
+
+                                Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { FunctionBundler, buildFunctionBundle } from "./lib/function-bundle.js";
+import { PullConfigOptions, PulledBranchConfig, PulledPreview, pullConfig } from "./lib/pull-config.js";
+import { PushConfigOptions, PushConfirmContext, pushConfig } from "./lib/push-config.js";
+import { ApplyOptions, ConfigOperationOptions, apply, inspect, plan } from "./lib/operations.js";
+import { AppliedChange, Config, ConfigLoadError, ConfigValidationError, ConflictReport, ErrorCode, LoadConfigOptions, MissingContextError, NeonApi, PlatformError, PushAbortedError, PushConflictError, PushResult, createNeonApiFromOptions, createRealNeonApi, defineConfig, loadConfigFromFile } from "./v1.js";
+export { AppliedChange, ApplyOptions, Config, ConfigLoadError, ConfigOperationOptions, ConfigValidationError, ConflictReport, ErrorCode, FunctionBundler, LoadConfigOptions, MissingContextError, NeonApi, PlatformError, PullConfigOptions, PulledBranchConfig, PulledPreview, PushAbortedError, PushConfigOptions, PushConfirmContext, PushConflictError, PushResult, apply, buildFunctionBundle, createNeonApiFromOptions, createRealNeonApi, defineConfig, inspect, loadConfigFromFile, plan, pullConfig, pushConfig };

package/dist/index.js

@@ -0,0 +1,6 @@
+import { buildFunctionBundle } from "./lib/function-bundle.js";
+import { pullConfig } from "./lib/pull-config.js";
+import { pushConfig } from "./lib/push-config.js";
+import { apply, inspect, plan } from "./lib/operations.js";
+import { ConfigLoadError, ConfigValidationError, ErrorCode, MissingContextError, PlatformError, PushAbortedError, PushConflictError, createNeonApiFromOptions, createRealNeonApi, defineConfig, loadConfigFromFile } from "./v1.js";
+export { ConfigLoadError, ConfigValidationError, ErrorCode, MissingContextError, PlatformError, PushAbortedError, PushConflictError, apply, buildFunctionBundle, createNeonApiFromOptions, createRealNeonApi, defineConfig, inspect, loadConfigFromFile, plan, pullConfig, pushConfig };

package/dist/lib/function-bundle.d.ts

@@ -0,0 +1,34 @@
+import { ResolvedFunctionConfig } from "@neondatabase/config";
+
+//#region src/lib/function-bundle.d.ts
+
+/**
+ * Builds the deployable ZIP bundle for a single function. The default
+ * implementation ({@link buildFunctionBundle}) shells out to esbuild, but
+ * `pushConfig` / `apply` accept a custom bundler so a consumer that can't ship
+ * esbuild's native binary (e.g. a single-file CLI) can supply its own — a WASM
+ * build, an esbuild binary on PATH, etc. — without this package dragging esbuild
+ * into their bundle.
+ */
+type FunctionBundler = (fn: ResolvedFunctionConfig) => Promise<Uint8Array>;
+/**
+ * Build the deployable bundle (a ZIP archive of the esbuild-bundled source) for a function.
+ *
+ * This is the **imperative shell** step of function deploys, and the reason it lives in
+ * `@neondatabase/config-runtime` rather than `@neondatabase/config`: it pulls in `esbuild`
+ * (a native binary) and `fflate`. Keeping it out of `@neondatabase/config` means a `neon.ts`
+ * that only imports `defineConfig` never drags esbuild into the user's dependency tree or
+ * bundle. Deploy-side consumers (the neonctl CLI, CI) import this package and get esbuild as
+ * a normal, auto-installed dependency.
+ *
+ * esbuild and fflate are loaded with a dynamic `import()` (not a static top-level import) so
+ * that nothing in this package's static graph names esbuild until a deploy actually runs —
+ * a second layer of protection on top of the package split.
+ *
+ * Mirrors: `esbuild <source> --bundle --outfile=out.js --sourcemap --minify`, then zips the
+ * emitted files into the archive the Functions deploy endpoint expects.
+ */
+declare function buildFunctionBundle(fn: ResolvedFunctionConfig): Promise<Uint8Array>;
+//#endregion
+export { FunctionBundler, buildFunctionBundle };
+//# sourceMappingURL=function-bundle.d.ts.map

package/dist/lib/function-bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"function-bundle.d.ts","names":[],"sources":["../../src/lib/function-bundle.ts"],"mappings":";;;;;;AAeA;;;;;AAEY;AAmBU,KArBV,eAAA,GAqB6B,CAAA,EAAA,EApBpC,sBAoBoC,EAAA,GAnBpC,OAmBoC,CAnB5B,UAmB4B,CAAA;;;;;AAE/B;;;;;;;;;;;;;iBAFY,mBAAA,KACjB,yBACF,QAAQ"}

package/dist/lib/function-bundle.js

@@ -0,0 +1,65 @@
+import { ErrorCode, PlatformError } from "@neondatabase/config";
+import { basename } from "node:path";
+//#region src/lib/function-bundle.ts
+/**
+* Build the deployable bundle (a ZIP archive of the esbuild-bundled source) for a function.
+*
+* This is the **imperative shell** step of function deploys, and the reason it lives in
+* `@neondatabase/config-runtime` rather than `@neondatabase/config`: it pulls in `esbuild`
+* (a native binary) and `fflate`. Keeping it out of `@neondatabase/config` means a `neon.ts`
+* that only imports `defineConfig` never drags esbuild into the user's dependency tree or
+* bundle. Deploy-side consumers (the neonctl CLI, CI) import this package and get esbuild as
+* a normal, auto-installed dependency.
+*
+* esbuild and fflate are loaded with a dynamic `import()` (not a static top-level import) so
+* that nothing in this package's static graph names esbuild until a deploy actually runs —
+* a second layer of protection on top of the package split.
+*
+* Mirrors: `esbuild <source> --bundle --outfile=out.js --sourcemap --minify`, then zips the
+* emitted files into the archive the Functions deploy endpoint expects.
+*/
+async function buildFunctionBundle(fn) {
+	const esbuild = await loadEsbuild();
+	let result;
+	try {
+		result = await esbuild.build({
+			entryPoints: [fn.source],
+			bundle: true,
+			write: false,
+			outfile: "out.js",
+			sourcemap: true,
+			minify: true,
+			format: "esm",
+			platform: "node",
+			packages: "external",
+			logLevel: "silent"
+		});
+	} catch (cause) {
+		throw new PlatformError(ErrorCode.InvalidConfig, [`Failed to bundle function "${fn.slug}" from ${fn.source}.`, cause?.message ?? String(cause)].join(" "), { cause });
+	}
+	const entries = {};
+	for (const file of result.outputFiles ?? []) entries[basename(file.path)] = file.contents;
+	return zipBundle(entries);
+}
+async function zipBundle(entries) {
+	const { zipSync } = await loadFflate();
+	return zipSync(entries, { level: 6 });
+}
+async function loadEsbuild() {
+	try {
+		return await import("esbuild");
+	} catch (cause) {
+		throw new PlatformError(ErrorCode.InvalidConfig, ["Deploying Neon Functions requires `esbuild`, which could not be loaded.", "It is a dependency of @neondatabase/config-runtime — reinstall your dependencies (`pnpm install` / `npm install`)."].join(" "), { cause });
+	}
+}
+async function loadFflate() {
+	try {
+		return await import("fflate");
+	} catch (cause) {
+		throw new PlatformError(ErrorCode.InvalidConfig, ["Deploying Neon Functions requires `fflate`, which could not be loaded.", "It is a dependency of @neondatabase/config-runtime — reinstall your dependencies (`pnpm install` / `npm install`)."].join(" "), { cause });
+	}
+}
+//#endregion
+export { buildFunctionBundle };
+
+//# sourceMappingURL=function-bundle.js.map

package/dist/lib/function-bundle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"function-bundle.js","names":[],"sources":["../../src/lib/function-bundle.ts"],"sourcesContent":["import { basename } from \"node:path\";\nimport {\n\tErrorCode,\n\tPlatformError,\n\ttype ResolvedFunctionConfig,\n} from \"@neondatabase/config\";\n\n/**\n * Builds the deployable ZIP bundle for a single function. The default\n * implementation ({@link buildFunctionBundle}) shells out to esbuild, but\n * `pushConfig` / `apply` accept a custom bundler so a consumer that can't ship\n * esbuild's native binary (e.g. a single-file CLI) can supply its own — a WASM\n * build, an esbuild binary on PATH, etc. — without this package dragging esbuild\n * into their bundle.\n */\nexport type FunctionBundler = (\n\tfn: ResolvedFunctionConfig,\n) => Promise<Uint8Array>;\n\n/**\n * Build the deployable bundle (a ZIP archive of the esbuild-bundled source) for a function.\n *\n * This is the **imperative shell** step of function deploys, and the reason it lives in\n * `@neondatabase/config-runtime` rather than `@neondatabase/config`: it pulls in `esbuild`\n * (a native binary) and `fflate`. Keeping it out of `@neondatabase/config` means a `neon.ts`\n * that only imports `defineConfig` never drags esbuild into the user's dependency tree or\n * bundle. Deploy-side consumers (the neonctl CLI, CI) import this package and get esbuild as\n * a normal, auto-installed dependency.\n *\n * esbuild and fflate are loaded with a dynamic `import()` (not a static top-level import) so\n * that nothing in this package's static graph names esbuild until a deploy actually runs —\n * a second layer of protection on top of the package split.\n *\n * Mirrors: `esbuild <source> --bundle --outfile=out.js --sourcemap --minify`, then zips the\n * emitted files into the archive the Functions deploy endpoint expects.\n */\nexport async function buildFunctionBundle(\n\tfn: ResolvedFunctionConfig,\n): Promise<Uint8Array> {\n\tconst esbuild = await loadEsbuild();\n\n\tlet result: Awaited<ReturnType<typeof esbuild.build>>;\n\ttry {\n\t\tresult = await esbuild.build({\n\t\t\tentryPoints: [fn.source],\n\t\t\tbundle: true,\n\t\t\twrite: false,\n\t\t\t// Set an explicit outfile so the emitted files are named `out.js` / `out.js.map`\n\t\t\t// (with `write: false` and no outfile, esbuild labels the buffer `<stdout>`).\n\t\t\toutfile: \"out.js\",\n\t\t\tsourcemap: true,\n\t\t\tminify: true,\n\t\t\tformat: \"esm\",\n\t\t\tplatform: \"node\",\n\t\t\t// The Functions runtime provides Node built-ins; don't try to bundle them.\n\t\t\tpackages: \"external\",\n\t\t\tlogLevel: \"silent\",\n\t\t});\n\t} catch (cause) {\n\t\tthrow new PlatformError(\n\t\t\tErrorCode.InvalidConfig,\n\t\t\t[\n\t\t\t\t`Failed to bundle function \"${fn.slug}\" from ${fn.source}.`,\n\t\t\t\t(cause as Error)?.message ?? String(cause),\n\t\t\t].join(\" \"),\n\t\t\t{ cause },\n\t\t);\n\t}\n\n\tconst entries: Record<string, Uint8Array> = {};\n\t// `write: false` guarantees `outputFiles`, but the type is optional — guard for safety.\n\tfor (const file of result.outputFiles ?? []) {\n\t\t// esbuild returns absolute output paths; archive them under their basename\n\t\t// (`out.js`, `out.js.map`) so the bundle layout is stable regardless of cwd.\n\t\tentries[basename(file.path)] = file.contents;\n\t}\n\n\treturn zipBundle(entries);\n}\n\nasync function zipBundle(\n\tentries: Record<string, Uint8Array>,\n): Promise<Uint8Array> {\n\tconst { zipSync } = await loadFflate();\n\treturn zipSync(entries, { level: 6 });\n}\n\nasync function loadEsbuild(): Promise<typeof import(\"esbuild\")> {\n\ttry {\n\t\treturn await import(\"esbuild\");\n\t} catch (cause) {\n\t\tthrow new PlatformError(\n\t\t\tErrorCode.InvalidConfig,\n\t\t\t[\n\t\t\t\t\"Deploying Neon Functions requires `esbuild`, which could not be loaded.\",\n\t\t\t\t\"It is a dependency of @neondatabase/config-runtime — reinstall your dependencies (`pnpm install` / `npm install`).\",\n\t\t\t].join(\" \"),\n\t\t\t{ cause },\n\t\t);\n\t}\n}\n\nasync function loadFflate(): Promise<typeof import(\"fflate\")> {\n\ttry {\n\t\treturn await import(\"fflate\");\n\t} catch (cause) {\n\t\tthrow new PlatformError(\n\t\t\tErrorCode.InvalidConfig,\n\t\t\t[\n\t\t\t\t\"Deploying Neon Functions requires `fflate`, which could not be loaded.\",\n\t\t\t\t\"It is a dependency of @neondatabase/config-runtime — reinstall your dependencies (`pnpm install` / `npm install`).\",\n\t\t\t].join(\" \"),\n\t\t\t{ cause },\n\t\t);\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAoCA,eAAsB,oBACrB,IACsB;CACtB,MAAM,UAAU,MAAM,YAAY;CAElC,IAAI;CACJ,IAAI;EACH,SAAS,MAAM,QAAQ,MAAM;GAC5B,aAAa,CAAC,GAAG,MAAM;GACvB,QAAQ;GACR,OAAO;GAGP,SAAS;GACT,WAAW;GACX,QAAQ;GACR,QAAQ;GACR,UAAU;GAEV,UAAU;GACV,UAAU;EACX,CAAC;CACF,SAAS,OAAO;EACf,MAAM,IAAI,cACT,UAAU,eACV,CACC,8BAA8B,GAAG,KAAK,SAAS,GAAG,OAAO,IACxD,OAAiB,WAAW,OAAO,KAAK,CAC1C,EAAE,KAAK,GAAG,GACV,EAAE,MAAM,CACT;CACD;CAEA,MAAM,UAAsC,CAAC;CAE7C,KAAK,MAAM,QAAQ,OAAO,eAAe,CAAC,GAGzC,QAAQ,SAAS,KAAK,IAAI,KAAK,KAAK;CAGrC,OAAO,UAAU,OAAO;AACzB;AAEA,eAAe,UACd,SACsB;CACtB,MAAM,EAAE,YAAY,MAAM,WAAW;CACrC,OAAO,QAAQ,SAAS,EAAE,OAAO,EAAE,CAAC;AACrC;AAEA,eAAe,cAAiD;CAC/D,IAAI;EACH,OAAO,MAAM,OAAO;CACrB,SAAS,OAAO;EACf,MAAM,IAAI,cACT,UAAU,eACV,CACC,2EACA,oHACD,EAAE,KAAK,GAAG,GACV,EAAE,MAAM,CACT;CACD;AACD;AAEA,eAAe,aAA+C;CAC7D,IAAI;EACH,OAAO,MAAM,OAAO;CACrB,SAAS,OAAO;EACf,MAAM,IAAI,cACT,UAAU,eACV,CACC,0EACA,oHACD,EAAE,KAAK,GAAG,GACV,EAAE,MAAM,CACT;CACD;AACD"}

package/dist/lib/operations.d.ts

@@ -0,0 +1,77 @@
+import { FunctionBundler } from "./function-bundle.js";
+import { PulledBranchConfig } from "./pull-config.js";
+import { PushConfigOptions } from "./push-config.js";
+import { Config, PushResult } from "@neondatabase/config";
+
+//#region src/lib/operations.d.ts
+
+/**
+ * Where to run the operation and how to authenticate. Filesystem- and env-agnostic: the
+ * `projectId` and `branchId` are always passed explicitly by the caller (e.g. neonctl
+ * resolves them from `.neon` / `NEON_*` and forwards them here).
+ */
+interface ConfigOperationOptions {
+  /**
+   * Neon project id. **Required** — the management API addresses branches through their
+   * project, so operations cannot run without it.
+   */
+  projectId: string;
+  /**
+   * Neon branch id (`br-…`). **Required.** Must already exist on the project; resolve
+   * branch names to ids before calling.
+   */
+  branchId: string;
+  /** Neon API key. Falls back to `NEON_API_KEY` / neonctl credentials. */
+  apiKey?: string;
+  /** Inject a custom NeonApi adapter (primarily for tests). */
+  api?: PushConfigOptions["api"];
+}
+/**
+ * Options accepted by {@link apply} on top of {@link ConfigOperationOptions}.
+ */
+interface ApplyOptions extends ConfigOperationOptions {
+  /**
+   * Auto-confirm overriding existing remote settings (TTL, `protected`, compute
+   * settings) on the selected branch. Without it, drift is reported as a conflict.
+   */
+  updateExisting?: boolean;
+  /** Auto-confirm applying to a branch marked `protected` on Neon. */
+  allowProtectedBranch?: boolean;
+  /**
+   * Custom function bundler. Defaults to esbuild (`buildFunctionBundle`); inject
+   * your own to deploy functions without pulling esbuild's native binary into
+   * your build. See {@link FunctionBundler}.
+   */
+  bundleFunction?: FunctionBundler;
+}
+/**
+ * Read a branch's live Neon state as a plain object (project + branch metadata and the
+ * reverse-engineered `BranchConfig`). Network read only — never mutates.
+ *
+ * `projectId` and `branchId` are **required** (both in `options`).
+ */
+declare function inspect(options: ConfigOperationOptions): Promise<PulledBranchConfig>;
+/**
+ * Compute what {@link apply} would do for the given branch without mutating anything
+ * (dry-run plan). Returns the full {@link PushResult} with the planned changes in
+ * `applied` and any blocking drift in `conflicts` — the Neon equivalent of
+ * `terraform plan`.
+ *
+ * `projectId` and `branchId` are **required** (both in `options`).
+ */
+declare function plan(config: Config, options: ConfigOperationOptions): Promise<PushResult>;
+/**
+ * Apply a `neon.ts` policy to the given Neon branch and return the {@link PushResult}
+ * describing what changed — the Neon equivalent of `terraform apply`.
+ *
+ * `projectId` and `branchId` are **required** (both in `options`). Pass `updateExisting`
+ * to auto-confirm overriding existing remote settings and `allowProtectedBranch` to
+ * auto-confirm applying to a protected branch; otherwise drift is reported as a
+ * `PushConflictError`.
+ *
+ * Never creates projects or branches — both must already exist.
+ */
+declare function apply(config: Config, options: ApplyOptions): Promise<PushResult>;
+//#endregion
+export { ApplyOptions, ConfigOperationOptions, apply, inspect, plan };
+//# sourceMappingURL=operations.d.ts.map

package/dist/lib/operations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.d.ts","names":[],"sources":["../../src/lib/operations.ts"],"mappings":";;;;;;;;;AAUA;AAoBA;;AAakB,UAjCD,sBAAA,CAiCC;;AAb0C;AAsB5D;;WACU,EAAA,MAAA;;;AACA;AAiBV;EAA0B,QAAA,EAAA,MAAA;;QAEhB,CAAA,EAAA,MAAA;;KACP,CAAA,EAlDI,iBAkDJ,CAAA,KAAA,CAAA;AAAO;AAuBV;;;AAEU,UArEO,YAAA,SAAqB,sBAqE5B,CAAA;;;AACA;;;;;;;;;;mBAzDQ;;;;;;;;iBASI,OAAA,UACZ,yBACP,QAAQ;;;;;;;;;iBAiBW,IAAA,SACb,iBACC,yBACP,QAAQ;;;;;;;;;;;;iBAuBW,KAAA,SACb,iBACC,eACP,QAAQ"}

package/dist/lib/operations.js

@@ -0,0 +1,61 @@
+import { pullConfig } from "./pull-config.js";
+import { pushConfig } from "./push-config.js";
+//#region src/lib/operations.ts
+/**
+* Read a branch's live Neon state as a plain object (project + branch metadata and the
+* reverse-engineered `BranchConfig`). Network read only — never mutates.
+*
+* `projectId` and `branchId` are **required** (both in `options`).
+*/
+async function inspect(options) {
+	return pullConfig({
+		projectId: options.projectId,
+		branchId: options.branchId,
+		...options.api ? { api: options.api } : {},
+		...options.apiKey ? { apiKey: options.apiKey } : {}
+	});
+}
+/**
+* Compute what {@link apply} would do for the given branch without mutating anything
+* (dry-run plan). Returns the full {@link PushResult} with the planned changes in
+* `applied` and any blocking drift in `conflicts` — the Neon equivalent of
+* `terraform plan`.
+*
+* `projectId` and `branchId` are **required** (both in `options`).
+*/
+async function plan(config, options) {
+	return pushConfig(config, {
+		projectId: options.projectId,
+		branchId: options.branchId,
+		dryRun: true,
+		updateExisting: true,
+		...options.api ? { api: options.api } : {},
+		...options.apiKey ? { apiKey: options.apiKey } : {}
+	});
+}
+/**
+* Apply a `neon.ts` policy to the given Neon branch and return the {@link PushResult}
+* describing what changed — the Neon equivalent of `terraform apply`.
+*
+* `projectId` and `branchId` are **required** (both in `options`). Pass `updateExisting`
+* to auto-confirm overriding existing remote settings and `allowProtectedBranch` to
+* auto-confirm applying to a protected branch; otherwise drift is reported as a
+* `PushConflictError`.
+*
+* Never creates projects or branches — both must already exist.
+*/
+async function apply(config, options) {
+	return pushConfig(config, {
+		projectId: options.projectId,
+		branchId: options.branchId,
+		...options.api ? { api: options.api } : {},
+		...options.apiKey ? { apiKey: options.apiKey } : {},
+		...options.updateExisting ? { updateExisting: true } : {},
+		...options.allowProtectedBranch ? { allowProtectedBranch: true } : {},
+		...options.bundleFunction ? { bundleFunction: options.bundleFunction } : {}
+	});
+}
+//#endregion
+export { apply, inspect, plan };
+
+//# sourceMappingURL=operations.js.map

package/dist/lib/operations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.js","names":[],"sources":["../../src/lib/operations.ts"],"sourcesContent":["import type { Config, PushResult } from \"@neondatabase/config\";\nimport type { FunctionBundler } from \"./function-bundle.js\";\nimport { type PulledBranchConfig, pullConfig } from \"./pull-config.js\";\nimport { type PushConfigOptions, pushConfig } from \"./push-config.js\";\n\n/**\n * Where to run the operation and how to authenticate. Filesystem- and env-agnostic: the\n * `projectId` and `branchId` are always passed explicitly by the caller (e.g. neonctl\n * resolves them from `.neon` / `NEON_*` and forwards them here).\n */\nexport interface ConfigOperationOptions {\n\t/**\n\t * Neon project id. **Required** — the management API addresses branches through their\n\t * project, so operations cannot run without it.\n\t */\n\tprojectId: string;\n\t/**\n\t * Neon branch id (`br-…`). **Required.** Must already exist on the project; resolve\n\t * branch names to ids before calling.\n\t */\n\tbranchId: string;\n\t/** Neon API key. Falls back to `NEON_API_KEY` / neonctl credentials. */\n\tapiKey?: string;\n\t/** Inject a custom NeonApi adapter (primarily for tests). */\n\tapi?: PushConfigOptions[\"api\"];\n}\n\n/**\n * Options accepted by {@link apply} on top of {@link ConfigOperationOptions}.\n */\nexport interface ApplyOptions extends ConfigOperationOptions {\n\t/**\n\t * Auto-confirm overriding existing remote settings (TTL, `protected`, compute\n\t * settings) on the selected branch. Without it, drift is reported as a conflict.\n\t */\n\tupdateExisting?: boolean;\n\t/** Auto-confirm applying to a branch marked `protected` on Neon. */\n\tallowProtectedBranch?: boolean;\n\t/**\n\t * Custom function bundler. Defaults to esbuild (`buildFunctionBundle`); inject\n\t * your own to deploy functions without pulling esbuild's native binary into\n\t * your build. See {@link FunctionBundler}.\n\t */\n\tbundleFunction?: FunctionBundler;\n}\n\n/**\n * Read a branch's live Neon state as a plain object (project + branch metadata and the\n * reverse-engineered `BranchConfig`). Network read only — never mutates.\n *\n * `projectId` and `branchId` are **required** (both in `options`).\n */\nexport async function inspect(\n\toptions: ConfigOperationOptions,\n): Promise<PulledBranchConfig> {\n\treturn pullConfig({\n\t\tprojectId: options.projectId,\n\t\tbranchId: options.branchId,\n\t\t...(options.api ? { api: options.api } : {}),\n\t\t...(options.apiKey ? { apiKey: options.apiKey } : {}),\n\t});\n}\n\n/**\n * Compute what {@link apply} would do for the given branch without mutating anything\n * (dry-run plan). Returns the full {@link PushResult} with the planned changes in\n * `applied` and any blocking drift in `conflicts` — the Neon equivalent of\n * `terraform plan`.\n *\n * `projectId` and `branchId` are **required** (both in `options`).\n */\nexport async function plan(\n\tconfig: Config,\n\toptions: ConfigOperationOptions,\n): Promise<PushResult> {\n\treturn pushConfig(config, {\n\t\tprojectId: options.projectId,\n\t\tbranchId: options.branchId,\n\t\tdryRun: true,\n\t\t// Surface the full would-apply list as plan steps without mutating anything.\n\t\tupdateExisting: true,\n\t\t...(options.api ? { api: options.api } : {}),\n\t\t...(options.apiKey ? { apiKey: options.apiKey } : {}),\n\t});\n}\n\n/**\n * Apply a `neon.ts` policy to the given Neon branch and return the {@link PushResult}\n * describing what changed — the Neon equivalent of `terraform apply`.\n *\n * `projectId` and `branchId` are **required** (both in `options`). Pass `updateExisting`\n * to auto-confirm overriding existing remote settings and `allowProtectedBranch` to\n * auto-confirm applying to a protected branch; otherwise drift is reported as a\n * `PushConflictError`.\n *\n * Never creates projects or branches — both must already exist.\n */\nexport async function apply(\n\tconfig: Config,\n\toptions: ApplyOptions,\n): Promise<PushResult> {\n\treturn pushConfig(config, {\n\t\tprojectId: options.projectId,\n\t\tbranchId: options.branchId,\n\t\t...(options.api ? { api: options.api } : {}),\n\t\t...(options.apiKey ? { apiKey: options.apiKey } : {}),\n\t\t...(options.updateExisting ? { updateExisting: true } : {}),\n\t\t...(options.allowProtectedBranch ? { allowProtectedBranch: true } : {}),\n\t\t...(options.bundleFunction\n\t\t\t? { bundleFunction: options.bundleFunction }\n\t\t\t: {}),\n\t});\n}\n"],"mappings":";;;;;;;;;AAoDA,eAAsB,QACrB,SAC8B;CAC9B,OAAO,WAAW;EACjB,WAAW,QAAQ;EACnB,UAAU,QAAQ;EAClB,GAAI,QAAQ,MAAM,EAAE,KAAK,QAAQ,IAAI,IAAI,CAAC;EAC1C,GAAI,QAAQ,SAAS,EAAE,QAAQ,QAAQ,OAAO,IAAI,CAAC;CACpD,CAAC;AACF;;;;;;;;;AAUA,eAAsB,KACrB,QACA,SACsB;CACtB,OAAO,WAAW,QAAQ;EACzB,WAAW,QAAQ;EACnB,UAAU,QAAQ;EAClB,QAAQ;EAER,gBAAgB;EAChB,GAAI,QAAQ,MAAM,EAAE,KAAK,QAAQ,IAAI,IAAI,CAAC;EAC1C,GAAI,QAAQ,SAAS,EAAE,QAAQ,QAAQ,OAAO,IAAI,CAAC;CACpD,CAAC;AACF;;;;;;;;;;;;AAaA,eAAsB,MACrB,QACA,SACsB;CACtB,OAAO,WAAW,QAAQ;EACzB,WAAW,QAAQ;EACnB,UAAU,QAAQ;EAClB,GAAI,QAAQ,MAAM,EAAE,KAAK,QAAQ,IAAI,IAAI,CAAC;EAC1C,GAAI,QAAQ,SAAS,EAAE,QAAQ,QAAQ,OAAO,IAAI,CAAC;EACnD,GAAI,QAAQ,iBAAiB,EAAE,gBAAgB,KAAK,IAAI,CAAC;EACzD,GAAI,QAAQ,uBAAuB,EAAE,sBAAsB,KAAK,IAAI,CAAC;EACrE,GAAI,QAAQ,iBACT,EAAE,gBAAgB,QAAQ,eAAe,IACzC,CAAC;CACL,CAAC;AACF"}

package/dist/lib/pull-config.d.ts

@@ -0,0 +1,63 @@
+import { BranchConfig, BucketConfig, NeonApi, NeonBranchSnapshot, NeonBucketSnapshot, NeonEndpointSnapshot, NeonFunctionSnapshot, NeonProjectSnapshot } from "@neondatabase/config";
+
+//#region src/lib/pull-config.d.ts
+interface PullConfigOptions {
+  /** Neon project id (`<project>`). Required — the API addresses branches by project. */
+  projectId: string;
+  /** Neon branch id (`br-…`). Required. Resolve names to ids before calling. */
+  branchId: string;
+  /** Neon API key. Falls back to `NEON_API_KEY` / neonctl credentials. */
+  apiKey?: string;
+  /** Inject a custom NeonApi adapter (primarily for tests). */
+  api?: NeonApi;
+}
+/**
+ * Live Preview-feature state read back from a branch. Surfaced alongside `config` rather
+ * than inside it because functions cannot round-trip: the remote only knows the deployed
+ * bundle, not the local `source` path a {@link FunctionConfig} requires, so a pulled
+ * function is reported as `{ slug, name }` (no `source`).
+ */
+interface PulledPreview {
+  buckets: BucketConfig[];
+  functions: Array<{
+    slug: string;
+    name: string;
+  }>;
+  aiGatewayEnabled: boolean;
+}
+interface PulledBranchConfig {
+  project: {
+    id: string;
+    name: string;
+    region: string;
+    pgVersion: number;
+    orgId?: string;
+  };
+  branch: {
+    id: string;
+    name: string;
+    parent?: string;
+    isDefault: boolean;
+    protected: boolean;
+    expiresAt?: string;
+  };
+  config: BranchConfig;
+  /**
+   * Live Preview-feature state, when the branch has any buckets/functions or an enabled
+   * AI Gateway. Omitted entirely when there is nothing to report.
+   */
+  preview?: PulledPreview;
+}
+declare function pullConfig(options: PullConfigOptions): Promise<PulledBranchConfig>;
+declare function buildPulledBranchConfig(project: NeonProjectSnapshot, branch: NeonBranchSnapshot, branches: NeonBranchSnapshot[], endpoint: NeonEndpointSnapshot | undefined, previewState?: {
+  buckets: NeonBucketSnapshot[];
+  functions: NeonFunctionSnapshot[];
+  aiGatewayEnabled: boolean;
+  /** Whether a Neon Auth integration is enabled on the branch. */
+  authEnabled?: boolean;
+  /** Whether a Neon Data API integration is enabled on the branch. */
+  dataApiEnabled?: boolean;
+}): PulledBranchConfig;
+//#endregion
+export { PullConfigOptions, PulledBranchConfig, PulledPreview, buildPulledBranchConfig, pullConfig };
+//# sourceMappingURL=pull-config.d.ts.map

package/dist/lib/pull-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pull-config.d.ts","names":[],"sources":["../../src/lib/pull-config.ts"],"mappings":";;;UAgBiB,iBAAA;;EAAA,SAAA,EAAA,MAAA;EAiBA;EAAa,QAAA,EAAA,MAAA;;QAElB,CAAA,EAAA,MAAA;EAAK;EAIA,GAAA,CAAA,EAfV,OAeU;;;;AAqBO;AAGxB;;;AAEW,UAhCM,aAAA,CAgCN;SAAR,EA/BO,YA+BP,EAAA;EAAO,SAAA,EA9BE,KA8BF,CAAA;IA0DM,IAAA,EAAA,MAAA;IAAuB,IAAA,EAAA,MAAA;;kBAE9B,EAAA,OAAA;;AAEE,UAxFM,kBAAA,CAwFN;SAEA,EAAA;IACE,EAAA,EAAA,MAAA;IAOV,IAAA,EAAA,MAAA;IAAkB,MAAA,EAAA,MAAA;;;;;;;;;;;;UAlFZ;;;;;YAKE;;iBAGW,UAAA,UACZ,oBACP,QAAQ;iBA0DK,uBAAA,UACN,6BACD,8BACE,gCACA;WAEA;aACE;;;;;;IAOV"}

package/dist/lib/pull-config.js

@@ -0,0 +1,113 @@
+import { ErrorCode, PlatformError, createNeonApiFromOptions } from "@neondatabase/config";
+//#region src/lib/pull-config.ts
+async function pullConfig(options) {
+	const api = options.api ?? createApiFromOptions(options);
+	const projectId = options.projectId;
+	const project = await api.getProject(projectId);
+	const [branches, endpoints] = await Promise.all([api.listBranches(projectId), api.listEndpoints(projectId)]);
+	const branch = resolveBranch(options.branchId, branches);
+	const endpoint = endpoints.find((ep) => ep.type === "read_write" && ep.branchId === branch.id);
+	const probeDatabase = pickProbeDatabase(await api.listBranchDatabases(projectId, branch.id));
+	const [buckets, functions, aiGatewayEnabled, auth, dataApi] = await Promise.all([
+		api.listBranchBuckets(projectId, branch.id),
+		api.listBranchFunctions(projectId, branch.id),
+		api.getAiGatewayEnabled(projectId, branch.id),
+		api.getNeonAuth(projectId, branch.id),
+		probeDatabase ? api.getNeonDataApi(projectId, branch.id, probeDatabase) : Promise.resolve(null)
+	]);
+	return buildPulledBranchConfig(project, branch, branches, endpoint, {
+		buckets,
+		functions,
+		aiGatewayEnabled,
+		authEnabled: auth !== null,
+		dataApiEnabled: dataApi !== null
+	});
+}
+/**
+* Pick the database to probe for a Data API integration. Data API is enabled per
+* branch + database; for read-back we only need to know whether *any* database has it
+* on, so prefer the conventional default (`neondb`) and otherwise fall back to the first
+* database. Returns `undefined` when the branch has no databases.
+*/
+function pickProbeDatabase(databases) {
+	if (databases.length === 0) return void 0;
+	const byName = databases.find((d) => d.name === "neondb");
+	if (byName) return byName.name;
+	return databases[0].name;
+}
+function createApiFromOptions(options) {
+	return createNeonApiFromOptions("pullConfig", { ...options.apiKey ? { apiKey: options.apiKey } : {} });
+}
+function buildPulledBranchConfig(project, branch, branches, endpoint, previewState) {
+	const parent = branch.parentId ? branches.find((b) => b.id === branch.parentId) : void 0;
+	const config = {
+		...previewState?.authEnabled ? { auth: {} } : {},
+		...previewState?.dataApiEnabled ? { dataApi: {} } : {}
+	};
+	if (parent) config.parent = parent.name;
+	if (branch.expiresAt) config.ttl = branch.expiresAt;
+	if (branch.protected) config.protected = true;
+	if (endpoint) {
+		const compute = endpointToComputeSettings(endpoint, project);
+		if (compute) config.postgres = { computeSettings: compute };
+	}
+	const result = {
+		project: {
+			id: project.id,
+			name: project.name,
+			region: project.regionId,
+			pgVersion: project.pgVersion,
+			...project.orgId ? { orgId: project.orgId } : {}
+		},
+		branch: {
+			id: branch.id,
+			name: branch.name,
+			...parent ? { parent: parent.name } : {},
+			isDefault: branch.isDefault,
+			protected: branch.protected,
+			...branch.expiresAt ? { expiresAt: branch.expiresAt } : {}
+		},
+		config
+	};
+	const preview = previewState ? buildPulledPreview(previewState) : void 0;
+	if (preview) result.preview = preview;
+	return result;
+}
+/**
+* Reverse-engineer the {@link PulledPreview} from remote snapshots. Returns `undefined` when
+* the branch has no Preview features so the field can be omitted entirely.
+*/
+function buildPulledPreview(state) {
+	if (state.buckets.length === 0 && state.functions.length === 0 && !state.aiGatewayEnabled) return;
+	return {
+		buckets: state.buckets.map((b) => ({
+			name: b.name,
+			access: b.accessLevel
+		})),
+		functions: state.functions.map((f) => ({
+			slug: f.slug,
+			name: f.name
+		})),
+		aiGatewayEnabled: state.aiGatewayEnabled
+	};
+}
+function resolveBranch(branchId, branches) {
+	const match = branches.find((b) => b.id === branchId);
+	if (match) return match;
+	throw new PlatformError(ErrorCode.BranchNotFound, [`pullConfig: branch id ${JSON.stringify(branchId)} not found on project.`, `Available branches: ${branches.map((b) => `${b.name} (${b.id})`).join(", ") || "(none)"}.`].join(" "), { details: {
+		branchId,
+		available: branches.map((b) => b.id)
+	} });
+}
+function endpointToComputeSettings(endpoint, project) {
+	const defaults = project.defaultEndpointSettings;
+	const out = {};
+	if (endpoint.autoscalingLimitMinCu !== void 0 && endpoint.autoscalingLimitMinCu !== defaults?.autoscalingLimitMinCu) out.autoscalingLimitMinCu = endpoint.autoscalingLimitMinCu;
+	if (endpoint.autoscalingLimitMaxCu !== void 0 && endpoint.autoscalingLimitMaxCu !== defaults?.autoscalingLimitMaxCu) out.autoscalingLimitMaxCu = endpoint.autoscalingLimitMaxCu;
+	if (endpoint.suspendTimeout !== void 0 && endpoint.suspendTimeout !== defaults?.suspendTimeout) out.suspendTimeout = endpoint.suspendTimeout;
+	return Object.keys(out).length > 0 ? out : void 0;
+}
+//#endregion
+export { buildPulledBranchConfig, pullConfig };
+
+//# sourceMappingURL=pull-config.js.map