@neon/config-runtime 0.0.0 → 0.8.1

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/README.md

@@ -0,0 +1,24 @@
+# @neon/config-runtime
+
+Imperative runtime for [`@neon/config`](../config): run a `neon.ts` policy against the Neon API — `inspect`, `plan`, `apply` (push/pull) — and bundle + deploy Neon Functions.
+
+> This package pulls in `esbuild`, so import it from your CLI or CI — **not** from a `neon.ts` policy. Keep policies side-effect-free; that's what `@neon/config` is for. New code should import from `@neon/config-runtime/v1` to pin a major.
+
+## Install
+
+```bash
+npm install @neon/config-runtime
+```
+
+## API
+
+- `inspect` / `plan` / `apply` — read the current branch state, diff a policy against it, and apply the changes.
+- `pullConfig` / `pushConfig` — lower-level pull/push primitives.
+- `createBranch` — create a branch to target.
+- `buildFunctionBundle` — bundle Neon Functions for deploy.
+
+```ts
+import { inspect, plan, apply } from "@neon/config-runtime/v1";
+```
+
+See [`@neon/config`](../config) for authoring the `neon.ts` policy these operate on.

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, CreateBranchOptions, CreateBranchResult, apply, createBranch, inspect, plan } from "./lib/operations.js";
+import { AppliedChange, Config, ConfigLoadError, ConfigValidationError, ConflictReport, ErrorCode, LoadConfigOptions, MissingContextError, NeonApi, PlatformError, PushAbortedError, PushConflictError, PushResult, createNeonApiFromOptions, createRealNeonApi, defineConfig, isPlatformError, loadConfigFromFile } from "./v1.js";
+export { AppliedChange, ApplyOptions, Config, ConfigLoadError, ConfigOperationOptions, ConfigValidationError, ConflictReport, CreateBranchOptions, CreateBranchResult, ErrorCode, FunctionBundler, LoadConfigOptions, MissingContextError, NeonApi, PlatformError, PullConfigOptions, PulledBranchConfig, PulledPreview, PushAbortedError, PushConfigOptions, PushConfirmContext, PushConflictError, PushResult, apply, buildFunctionBundle, createBranch, createNeonApiFromOptions, createRealNeonApi, defineConfig, inspect, isPlatformError, 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, createBranch, inspect, plan } from "./lib/operations.js";
+import { ConfigLoadError, ConfigValidationError, ErrorCode, MissingContextError, PlatformError, PushAbortedError, PushConflictError, createNeonApiFromOptions, createRealNeonApi, defineConfig, isPlatformError, loadConfigFromFile } from "./v1.js";
+export { ConfigLoadError, ConfigValidationError, ErrorCode, MissingContextError, PlatformError, PushAbortedError, PushConflictError, apply, buildFunctionBundle, createBranch, createNeonApiFromOptions, createRealNeonApi, defineConfig, inspect, isPlatformError, loadConfigFromFile, plan, pullConfig, pushConfig };

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

@@ -0,0 +1,40 @@
+import { ResolvedFunctionConfig } from "@neon/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
+ * `@neon/config-runtime` rather than `@neon/config`: it pulls in `esbuild`
+ * (a native binary) and `fflate`. Keeping it out of `@neon/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=index.mjs --minify --format=esm
+ * --platform=node --banner:js=<createRequire shim>`, then zips the emitted files into the
+ * archive the Functions deploy endpoint expects. Dependencies are bundled into the entry
+ * (Node built-ins stay external); see {@link ESM_CJS_INTEROP_BANNER} for why the banner.
+ *
+ * No source map is emitted: the Functions runtime does not run Node with source-map support,
+ * so an uploaded `index.mjs.map` is never consumed (a thrown error's stack still points into
+ * the minified bundle). Generating it only inflated the deployed archive, so it is omitted.
+ */
+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;AAmCU,KArCV,eAAA,GAqC6B,CAAA,EAAA,EApCpC,sBAoCoC,EAAA,GAnCpC,OAmCoC,CAnC5B,UAmC4B,CAAA;;;;;AAE/B;;;;;;;;;;;;;;;;;;;iBAFY,mBAAA,KACjB,yBACF,QAAQ"}

package/dist/lib/function-bundle.js

@@ -0,0 +1,78 @@
+import { ErrorCode, PlatformError } from "@neon/config";
+import { basename } from "node:path";
+//#region src/lib/function-bundle.ts
+/**
+* Prepended to the ESM bundle. Bundled dependencies are frequently CommonJS, but an ESM
+* output (`format: "esm"`) has no `require` / `__filename` / `__dirname` in scope — so any
+* bundled CJS code that calls `require(...)` would fail at load with
+* `Dynamic require of "x" is not supported`. Re-create those globals via `createRequire`
+* so CJS and ESM dependencies coexist in the single `index.mjs`.
+*/
+const ESM_CJS_INTEROP_BANNER = "import{createRequire as ___cr}from'module';import{fileURLToPath as ___f}from'url';import{dirname as ___d}from'path';const require=___cr(import.meta.url);const __filename=___f(import.meta.url);const __dirname=___d(__filename);";
+/**
+* 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
+* `@neon/config-runtime` rather than `@neon/config`: it pulls in `esbuild`
+* (a native binary) and `fflate`. Keeping it out of `@neon/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=index.mjs --minify --format=esm
+* --platform=node --banner:js=<createRequire shim>`, then zips the emitted files into the
+* archive the Functions deploy endpoint expects. Dependencies are bundled into the entry
+* (Node built-ins stay external); see {@link ESM_CJS_INTEROP_BANNER} for why the banner.
+*
+* No source map is emitted: the Functions runtime does not run Node with source-map support,
+* so an uploaded `index.mjs.map` is never consumed (a thrown error's stack still points into
+* the minified bundle). Generating it only inflated the deployed archive, so it is omitted.
+*/
+async function buildFunctionBundle(fn) {
+	const esbuild = await loadEsbuild();
+	let result;
+	try {
+		result = await esbuild.build({
+			entryPoints: [fn.source],
+			bundle: true,
+			write: false,
+			outfile: "index.mjs",
+			minify: true,
+			format: "esm",
+			platform: "node",
+			banner: { js: ESM_CJS_INTEROP_BANNER },
+			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 @neon/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 @neon/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 \"@neon/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 * Prepended to the ESM bundle. Bundled dependencies are frequently CommonJS, but an ESM\n * output (`format: \"esm\"`) has no `require` / `__filename` / `__dirname` in scope — so any\n * bundled CJS code that calls `require(...)` would fail at load with\n * `Dynamic require of \"x\" is not supported`. Re-create those globals via `createRequire`\n * so CJS and ESM dependencies coexist in the single `index.mjs`.\n */\nconst ESM_CJS_INTEROP_BANNER =\n\t\"import{createRequire as ___cr}from'module';import{fileURLToPath as ___f}from'url';import{dirname as ___d}from'path';const require=___cr(import.meta.url);const __filename=___f(import.meta.url);const __dirname=___d(__filename);\";\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 * `@neon/config-runtime` rather than `@neon/config`: it pulls in `esbuild`\n * (a native binary) and `fflate`. Keeping it out of `@neon/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=index.mjs --minify --format=esm\n * --platform=node --banner:js=<createRequire shim>`, then zips the emitted files into the\n * archive the Functions deploy endpoint expects. Dependencies are bundled into the entry\n * (Node built-ins stay external); see {@link ESM_CJS_INTEROP_BANNER} for why the banner.\n *\n * No source map is emitted: the Functions runtime does not run Node with source-map support,\n * so an uploaded `index.mjs.map` is never consumed (a thrown error's stack still points into\n * the minified bundle). Generating it only inflated the deployed archive, so it is omitted.\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// Emit `index.mjs`: the Functions runtime imports the archive's entry by the\n\t\t\t// conventional `index.{js,mjs}` name, and `.mjs` makes Node load the ESM output\n\t\t\t// directly. (With `write: false` and no outfile, esbuild would label the buffer\n\t\t\t// `<stdout>`.) No `sourcemap` — see the doc comment above for why.\n\t\t\toutfile: \"index.mjs\",\n\t\t\tminify: true,\n\t\t\tformat: \"esm\",\n\t\t\tplatform: \"node\",\n\t\t\t// Bundle dependencies into the entry so the deployed archive is self-contained\n\t\t\t// (the Functions runtime has no node_modules). Node built-ins stay external on\n\t\t\t// `platform: \"node\"`. The banner re-creates require/__filename/__dirname so\n\t\t\t// bundled CommonJS deps work inside the ESM output.\n\t\t\tbanner: { js: ESM_CJS_INTEROP_BANNER },\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// (`index.mjs`) 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 @neon/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 @neon/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":";;;;;;;;;;AA0BA,MAAM,yBACL;;;;;;;;;;;;;;;;;;;;;;;;AAyBD,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;GAKP,SAAS;GACT,QAAQ;GACR,QAAQ;GACR,UAAU;GAKV,QAAQ,EAAE,IAAI,uBAAuB;GACrC,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,CAAC,CAAC,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,4GACD,CAAC,CAAC,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,4GACD,CAAC,CAAC,KAAK,GAAG,GACV,EAAE,MAAM,CACT;CACD;AACD"}

package/dist/lib/operations.d.ts

@@ -0,0 +1,125 @@
+import { FunctionBundler } from "./function-bundle.js";
+import { PulledBranchConfig } from "./pull-config.js";
+import { PushConfigOptions } from "./push-config.js";
+import { Config, NeonApi, PushResult } from "@neon/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;
+  /** Neon API base URL. Falls back to `NEON_API_HOST`, then production. */
+  apiHost?: 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>;
+/**
+ * Options accepted by {@link createBranch}. Unlike {@link ConfigOperationOptions} this takes a
+ * branch **name** (the branch does not exist yet) rather than an id.
+ */
+interface CreateBranchOptions {
+  /** Neon project id to create the branch in. **Required.** */
+  projectId: string;
+  /** Name of the branch to create. **Required.** Must not already exist on the project. */
+  branchName: string;
+  /** Neon API key. Falls back to `NEON_API_KEY` / neonctl credentials. Ignored when `api` is set. */
+  apiKey?: string;
+  /** Inject a custom NeonApi adapter (primarily for tests). */
+  api?: NeonApi;
+  /** Custom function bundler (defaults to esbuild). See {@link FunctionBundler}. */
+  bundleFunction?: FunctionBundler;
+}
+/**
+ * Result of {@link createBranch}: the created branch's id/name plus the {@link PushResult}
+ * describing the policy that was applied to it.
+ */
+interface CreateBranchResult {
+  branchId: string;
+  branchName: string;
+  /** What applying the policy to the freshly created branch changed. */
+  result: PushResult;
+}
+/**
+ * Create a Neon branch **from a `neon.ts` policy** and bring it up with its declared
+ * settings/infra in one step — the operation `neonctl checkout <new-name>` needs.
+ *
+ * The flow is the one a creation actually wants:
+ *  1. Evaluate the policy for the new branch with `exists: false` (so creation-time tuning —
+ *     `parent`, `ttl`, compute settings, `protected` — resolves instead of the
+ *     "existing branch, leave as-is" path most policies guard with `if (branch.exists)`).
+ *  2. Create the branch, branched from the policy's `parent` (falling back to the project's
+ *     default branch).
+ *  3. {@link pushConfig} the policy onto it with `branchExists: false`, so TTL / compute /
+ *     `protected` and the services (Neon Auth, Data API, functions) are applied.
+ *
+ * This is why `apply` alone couldn't do it: `apply` operates on an *existing* branch
+ * (`exists: true`), so a policy keyed on `!branch.exists` never returns the creation tuning.
+ *
+ * Throws {@link PlatformError} (`Conflict`) if a branch with `branchName` already exists, or
+ * (`BranchNotFound`) if the policy names a `parent` that isn't on the project.
+ */
+declare function createBranch(config: Config, options: CreateBranchOptions): Promise<CreateBranchResult>;
+//#endregion
+export { ApplyOptions, ConfigOperationOptions, CreateBranchOptions, CreateBranchResult, apply, createBranch, 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":";;;;;;;;;AAmBA;AAsBA;;AAakB,UAnCD,sBAAA,CAmCC;;AAb0C;AAsB5D;;WACU,EAAA,MAAA;;;AACA;AAkBV;EAA0B,QAAA,EAAA,MAAA;;QAEhB,CAAA,EAAA,MAAA;;SACP,CAAA,EAAA,MAAA;EAAO;EAwBY,GAAA,CAAA,EA3Ef,iBA2EoB,CAAA,KAAA,CAAA;;;;;AAGxB,UAxEc,YAAA,SAAqB,sBAwEnC,CAAA;EAAO;AAmBV;;;gBAUkB,CAAA,EAAA,OAAA;EAAe;EAOhB,oBAAA,CAAkB,EAAA,OAAA;EA0Bb;;;;;gBAGnB,CAAA,EA5He,eA4Hf;AAAO;;;;;;;iBAnHY,OAAA,UACZ,yBACP,QAAQ;;;;;;;;;iBAkBW,IAAA,SACb,iBACC,yBACP,QAAQ;;;;;;;;;;;;iBAwBW,KAAA,SACb,iBACC,eACP,QAAQ;;;;;UAmBM,mBAAA;;;;;;;;QAQV;;mBAEW;;;;;;UAOD,kBAAA;;;;UAIR;;;;;;;;;;;;;;;;;;;;;iBAsBa,YAAA,SACb,iBACC,sBACP,QAAQ"}

package/dist/lib/operations.js

@@ -0,0 +1,133 @@
+import { pullConfig } from "./pull-config.js";
+import { pushConfig } from "./push-config.js";
+import { ErrorCode, PlatformError, createNeonApiFromOptions, resolveConfig } from "@neon/config";
+//#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 } : {},
+		...options.apiHost ? { apiHost: options.apiHost } : {}
+	});
+}
+/**
+* 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 } : {},
+		...options.apiHost ? { apiHost: options.apiHost } : {}
+	});
+}
+/**
+* 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.apiHost ? { apiHost: options.apiHost } : {},
+		...options.updateExisting ? { updateExisting: true } : {},
+		...options.allowProtectedBranch ? { allowProtectedBranch: true } : {},
+		...options.bundleFunction ? { bundleFunction: options.bundleFunction } : {}
+	});
+}
+/**
+* Create a Neon branch **from a `neon.ts` policy** and bring it up with its declared
+* settings/infra in one step — the operation `neonctl checkout <new-name>` needs.
+*
+* The flow is the one a creation actually wants:
+*  1. Evaluate the policy for the new branch with `exists: false` (so creation-time tuning —
+*     `parent`, `ttl`, compute settings, `protected` — resolves instead of the
+*     "existing branch, leave as-is" path most policies guard with `if (branch.exists)`).
+*  2. Create the branch, branched from the policy's `parent` (falling back to the project's
+*     default branch).
+*  3. {@link pushConfig} the policy onto it with `branchExists: false`, so TTL / compute /
+*     `protected` and the services (Neon Auth, Data API, functions) are applied.
+*
+* This is why `apply` alone couldn't do it: `apply` operates on an *existing* branch
+* (`exists: true`), so a policy keyed on `!branch.exists` never returns the creation tuning.
+*
+* Throws {@link PlatformError} (`Conflict`) if a branch with `branchName` already exists, or
+* (`BranchNotFound`) if the policy names a `parent` that isn't on the project.
+*/
+async function createBranch(config, options) {
+	const api = options.api ?? createNeonApiFromOptions("createBranch", options.apiKey ? { apiKey: options.apiKey } : {});
+	const { projectId, branchName } = options;
+	const branches = await api.listBranches(projectId);
+	if (branches.some((b) => b.name === branchName)) throw new PlatformError(ErrorCode.Conflict, `createBranch: a branch named "${branchName}" already exists on project ${projectId}. Pick a different name or check it out instead of creating it.`, { details: {
+		projectId,
+		branchName
+	} });
+	const parentId = resolveParentBranchId(resolveConfig(config, {
+		name: branchName,
+		exists: false
+	}).parent, branches, branchName);
+	const { branch } = await api.createBranch(projectId, {
+		name: branchName,
+		...parentId ? { parentId } : {}
+	});
+	const result = await pushConfig(config, {
+		projectId,
+		branchId: branch.id,
+		api,
+		branchExists: false,
+		updateExisting: true,
+		allowProtectedBranch: true,
+		...options.bundleFunction ? { bundleFunction: options.bundleFunction } : {}
+	});
+	return {
+		branchId: branch.id,
+		branchName: branch.name,
+		result
+	};
+}
+/**
+* Resolve the parent branch id for a new branch. A policy-declared `parent` (a branch name) is
+* looked up by name; an unknown name is a hard error. With no `parent`, fall back to the
+* project's default branch, or `undefined` (let the API pick the project default) when none is
+* marked default.
+*/
+function resolveParentBranchId(parentName, branches, branchName) {
+	if (parentName !== void 0) {
+		const match = branches.find((b) => b.name === parentName);
+		if (!match) throw new PlatformError(ErrorCode.BranchNotFound, `createBranch: the policy for "${branchName}" sets parent "${parentName}", but no branch with that name exists. Existing branches: ${branches.map((b) => b.name).join(", ") || "(none)"}.`, { details: {
+			branchName,
+			parent: parentName,
+			available: branches.map((b) => b.name)
+		} });
+		return match.id;
+	}
+	return branches.find((b) => b.isDefault)?.id;
+}
+//#endregion
+export { apply, createBranch, 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 {\n\ttype Config,\n\tcreateNeonApiFromOptions,\n\tErrorCode,\n\ttype NeonApi,\n\ttype NeonBranchSnapshot,\n\tPlatformError,\n\ttype PushResult,\n\tresolveConfig,\n} from \"@neon/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/** Neon API base URL. Falls back to `NEON_API_HOST`, then production. */\n\tapiHost?: 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\t...(options.apiHost ? { apiHost: options.apiHost } : {}),\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\t...(options.apiHost ? { apiHost: options.apiHost } : {}),\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.apiHost ? { apiHost: options.apiHost } : {}),\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\n/**\n * Options accepted by {@link createBranch}. Unlike {@link ConfigOperationOptions} this takes a\n * branch **name** (the branch does not exist yet) rather than an id.\n */\nexport interface CreateBranchOptions {\n\t/** Neon project id to create the branch in. **Required.** */\n\tprojectId: string;\n\t/** Name of the branch to create. **Required.** Must not already exist on the project. */\n\tbranchName: string;\n\t/** Neon API key. Falls back to `NEON_API_KEY` / neonctl credentials. Ignored when `api` is set. */\n\tapiKey?: string;\n\t/** Inject a custom NeonApi adapter (primarily for tests). */\n\tapi?: NeonApi;\n\t/** Custom function bundler (defaults to esbuild). See {@link FunctionBundler}. */\n\tbundleFunction?: FunctionBundler;\n}\n\n/**\n * Result of {@link createBranch}: the created branch's id/name plus the {@link PushResult}\n * describing the policy that was applied to it.\n */\nexport interface CreateBranchResult {\n\tbranchId: string;\n\tbranchName: string;\n\t/** What applying the policy to the freshly created branch changed. */\n\tresult: PushResult;\n}\n\n/**\n * Create a Neon branch **from a `neon.ts` policy** and bring it up with its declared\n * settings/infra in one step — the operation `neonctl checkout <new-name>` needs.\n *\n * The flow is the one a creation actually wants:\n *  1. Evaluate the policy for the new branch with `exists: false` (so creation-time tuning —\n *     `parent`, `ttl`, compute settings, `protected` — resolves instead of the\n *     \"existing branch, leave as-is\" path most policies guard with `if (branch.exists)`).\n *  2. Create the branch, branched from the policy's `parent` (falling back to the project's\n *     default branch).\n *  3. {@link pushConfig} the policy onto it with `branchExists: false`, so TTL / compute /\n *     `protected` and the services (Neon Auth, Data API, functions) are applied.\n *\n * This is why `apply` alone couldn't do it: `apply` operates on an *existing* branch\n * (`exists: true`), so a policy keyed on `!branch.exists` never returns the creation tuning.\n *\n * Throws {@link PlatformError} (`Conflict`) if a branch with `branchName` already exists, or\n * (`BranchNotFound`) if the policy names a `parent` that isn't on the project.\n */\nexport async function createBranch(\n\tconfig: Config,\n\toptions: CreateBranchOptions,\n): Promise<CreateBranchResult> {\n\tconst api =\n\t\toptions.api ??\n\t\tcreateNeonApiFromOptions(\n\t\t\t\"createBranch\",\n\t\t\toptions.apiKey ? { apiKey: options.apiKey } : {},\n\t\t);\n\tconst { projectId, branchName } = options;\n\n\tconst branches = await api.listBranches(projectId);\n\tif (branches.some((b) => b.name === branchName)) {\n\t\tthrow new PlatformError(\n\t\t\tErrorCode.Conflict,\n\t\t\t`createBranch: a branch named \"${branchName}\" already exists on project ${projectId}. Pick a different name or check it out instead of creating it.`,\n\t\t\t{ details: { projectId, branchName } },\n\t\t);\n\t}\n\n\t// Evaluate the policy as a creation so `parent` (only settable at create time) resolves.\n\tconst resolved = resolveConfig(config, {\n\t\tname: branchName,\n\t\texists: false,\n\t});\n\tconst parentId = resolveParentBranchId(\n\t\tresolved.parent,\n\t\tbranches,\n\t\tbranchName,\n\t);\n\n\tconst { branch } = await api.createBranch(projectId, {\n\t\tname: branchName,\n\t\t...(parentId ? { parentId } : {}),\n\t});\n\n\t// Reconcile the rest as a new branch (`branchExists: false`): TTL, compute settings,\n\t// `protected`, and the services/functions the policy declares are applied onto the\n\t// freshly created branch. `updateExisting`/`allowProtectedBranch` are safe here — there is\n\t// no pre-existing state a user would be surprised to see overridden.\n\tconst result = await pushConfig(config, {\n\t\tprojectId,\n\t\tbranchId: branch.id,\n\t\tapi,\n\t\tbranchExists: false,\n\t\tupdateExisting: true,\n\t\tallowProtectedBranch: true,\n\t\t...(options.bundleFunction\n\t\t\t? { bundleFunction: options.bundleFunction }\n\t\t\t: {}),\n\t});\n\n\treturn { branchId: branch.id, branchName: branch.name, result };\n}\n\n/**\n * Resolve the parent branch id for a new branch. A policy-declared `parent` (a branch name) is\n * looked up by name; an unknown name is a hard error. With no `parent`, fall back to the\n * project's default branch, or `undefined` (let the API pick the project default) when none is\n * marked default.\n */\nfunction resolveParentBranchId(\n\tparentName: string | undefined,\n\tbranches: NeonBranchSnapshot[],\n\tbranchName: string,\n): string | undefined {\n\tif (parentName !== undefined) {\n\t\tconst match = branches.find((b) => b.name === parentName);\n\t\tif (!match) {\n\t\t\tthrow new PlatformError(\n\t\t\t\tErrorCode.BranchNotFound,\n\t\t\t\t`createBranch: the policy for \"${branchName}\" sets parent \"${parentName}\", but no branch with that name exists. Existing branches: ${\n\t\t\t\t\tbranches.map((b) => b.name).join(\", \") || \"(none)\"\n\t\t\t\t}.`,\n\t\t\t\t{\n\t\t\t\t\tdetails: {\n\t\t\t\t\t\tbranchName,\n\t\t\t\t\t\tparent: parentName,\n\t\t\t\t\t\tavailable: branches.map((b) => b.name),\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t);\n\t\t}\n\t\treturn match.id;\n\t}\n\treturn branches.find((b) => b.isDefault)?.id;\n}\n"],"mappings":";;;;;;;;;;AA+DA,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;EACnD,GAAI,QAAQ,UAAU,EAAE,SAAS,QAAQ,QAAQ,IAAI,CAAC;CACvD,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;EACnD,GAAI,QAAQ,UAAU,EAAE,SAAS,QAAQ,QAAQ,IAAI,CAAC;CACvD,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,UAAU,EAAE,SAAS,QAAQ,QAAQ,IAAI,CAAC;EACtD,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;;;;;;;;;;;;;;;;;;;;AAiDA,eAAsB,aACrB,QACA,SAC8B;CAC9B,MAAM,MACL,QAAQ,OACR,yBACC,gBACA,QAAQ,SAAS,EAAE,QAAQ,QAAQ,OAAO,IAAI,CAAC,CAChD;CACD,MAAM,EAAE,WAAW,eAAe;CAElC,MAAM,WAAW,MAAM,IAAI,aAAa,SAAS;CACjD,IAAI,SAAS,MAAM,MAAM,EAAE,SAAS,UAAU,GAC7C,MAAM,IAAI,cACT,UAAU,UACV,iCAAiC,WAAW,8BAA8B,UAAU,kEACpF,EAAE,SAAS;EAAE;EAAW;CAAW,EAAE,CACtC;CAQD,MAAM,WAAW,sBAJA,cAAc,QAAQ;EACtC,MAAM;EACN,QAAQ;CACT,CAEQ,CAAC,CAAC,QACT,UACA,UACD;CAEA,MAAM,EAAE,WAAW,MAAM,IAAI,aAAa,WAAW;EACpD,MAAM;EACN,GAAI,WAAW,EAAE,SAAS,IAAI,CAAC;CAChC,CAAC;CAMD,MAAM,SAAS,MAAM,WAAW,QAAQ;EACvC;EACA,UAAU,OAAO;EACjB;EACA,cAAc;EACd,gBAAgB;EAChB,sBAAsB;EACtB,GAAI,QAAQ,iBACT,EAAE,gBAAgB,QAAQ,eAAe,IACzC,CAAC;CACL,CAAC;CAED,OAAO;EAAE,UAAU,OAAO;EAAI,YAAY,OAAO;EAAM;CAAO;AAC/D;;;;;;;AAQA,SAAS,sBACR,YACA,UACA,YACqB;CACrB,IAAI,eAAe,KAAA,GAAW;EAC7B,MAAM,QAAQ,SAAS,MAAM,MAAM,EAAE,SAAS,UAAU;EACxD,IAAI,CAAC,OACJ,MAAM,IAAI,cACT,UAAU,gBACV,iCAAiC,WAAW,iBAAiB,WAAW,6DACvE,SAAS,KAAK,MAAM,EAAE,IAAI,CAAC,CAAC,KAAK,IAAI,KAAK,SAC1C,IACD,EACC,SAAS;GACR;GACA,QAAQ;GACR,WAAW,SAAS,KAAK,MAAM,EAAE,IAAI;EACtC,EACD,CACD;EAED,OAAO,MAAM;CACd;CACA,OAAO,SAAS,MAAM,MAAM,EAAE,SAAS,CAAC,EAAE;AAC3C"}