@neon/config-runtime 0.12.5 → 1.0.0

package/README.md

@@ -17,7 +17,10 @@ npm install @neon/config-runtime
 - `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. Honours the function's `externalPackages`, passing each entry to esbuild's `external`.
+- `buildFunctionBundle` — bundle Neon Functions for deploy. Honours the function's `externalPackages`: every entry is passed to esbuild's `external`, and unless it sets `includeFiles: false` the package's real files are staged into the archive alongside the bundle. Reports a bundled-in native dependency that was never declared, as a warning.
+- `traceNativePackages` — install the packages a function stages for the runtime target (`RUNTIME_TARGET`: linux-arm64, glibc) into a throwaway directory, trace the files they reach, and return them keyed by archive path with the `node_modules` layout preserved. Called by `buildFunctionBundle`; exported for a CLI that supplies its own bundler.
+- `findUndeclaredNativePackages` / `describeNativeFinding` — advisory detection of a native package that was bundled in without being declared, and the report text for it. Evidence only: it cannot prove the code path is reached, so it must never fail a deploy.
+- `assertZipWithinLimits` — check a finished archive against the build service's size limits (`DEFAULT_ARCHIVE_LIMITS`), with an error naming the largest files.
 
 ```ts
 import { inspect, plan, apply } from "@neon/config-runtime/v1";

package/dist/index.d.ts

@@ -1,6 +1,8 @@
+import { ArchiveLimits, DEFAULT_ARCHIVE_LIMITS, NativeTraceDeps, NativeTraceResult, RUNTIME_TARGET, RUNTIME_TARGET_LABEL, assertZipWithinLimits, enforceLimits, traceNativePackages } from "./lib/native-packages.js";
 import { FunctionBundler, buildFunctionBundle } from "./lib/function-bundle.js";
+import { NativeEvidence, NativeFinding, describeNativeFinding, findUndeclaredNativePackages } from "./lib/native-detect.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, PartialBranchCreateError, PlatformError, PushAbortedError, PushConflictError, PushResult, createNeonApiFromOptions, createRealNeonApi, defineConfig, isPartialBranchCreateError, isPlatformError, loadConfigFromFile } from "./v1.js";
-export { AppliedChange, ApplyOptions, Config, ConfigLoadError, ConfigOperationOptions, ConfigValidationError, ConflictReport, CreateBranchOptions, CreateBranchResult, ErrorCode, FunctionBundler, LoadConfigOptions, MissingContextError, NeonApi, PartialBranchCreateError, PlatformError, PullConfigOptions, PulledBranchConfig, PulledPreview, PushAbortedError, PushConfigOptions, PushConfirmContext, PushConflictError, PushResult, apply, buildFunctionBundle, createBranch, createNeonApiFromOptions, createRealNeonApi, defineConfig, inspect, isPartialBranchCreateError, isPlatformError, loadConfigFromFile, plan, pullConfig, pushConfig };
+export { AppliedChange, ApplyOptions, ArchiveLimits, Config, ConfigLoadError, ConfigOperationOptions, ConfigValidationError, ConflictReport, CreateBranchOptions, CreateBranchResult, DEFAULT_ARCHIVE_LIMITS, ErrorCode, FunctionBundler, LoadConfigOptions, MissingContextError, NativeEvidence, NativeFinding, NativeTraceDeps, NativeTraceResult, NeonApi, PartialBranchCreateError, PlatformError, PullConfigOptions, PulledBranchConfig, PulledPreview, PushAbortedError, PushConfigOptions, PushConfirmContext, PushConflictError, PushResult, RUNTIME_TARGET, RUNTIME_TARGET_LABEL, apply, assertZipWithinLimits, buildFunctionBundle, createBranch, createNeonApiFromOptions, createRealNeonApi, defineConfig, describeNativeFinding, enforceLimits, findUndeclaredNativePackages, inspect, isPartialBranchCreateError, isPlatformError, loadConfigFromFile, plan, pullConfig, pushConfig, traceNativePackages };

package/dist/index.js

@@ -1,6 +1,8 @@
+import { DEFAULT_ARCHIVE_LIMITS, RUNTIME_TARGET, RUNTIME_TARGET_LABEL, assertZipWithinLimits, enforceLimits, traceNativePackages } from "./lib/native-packages.js";
+import { describeNativeFinding, findUndeclaredNativePackages } from "./lib/native-detect.js";
 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, PartialBranchCreateError, PlatformError, PushAbortedError, PushConflictError, createNeonApiFromOptions, createRealNeonApi, defineConfig, isPartialBranchCreateError, isPlatformError, loadConfigFromFile } from "./v1.js";
-export { ConfigLoadError, ConfigValidationError, ErrorCode, MissingContextError, PartialBranchCreateError, PlatformError, PushAbortedError, PushConflictError, apply, buildFunctionBundle, createBranch, createNeonApiFromOptions, createRealNeonApi, defineConfig, inspect, isPartialBranchCreateError, isPlatformError, loadConfigFromFile, plan, pullConfig, pushConfig };
+export { ConfigLoadError, ConfigValidationError, DEFAULT_ARCHIVE_LIMITS, ErrorCode, MissingContextError, PartialBranchCreateError, PlatformError, PushAbortedError, PushConflictError, RUNTIME_TARGET, RUNTIME_TARGET_LABEL, apply, assertZipWithinLimits, buildFunctionBundle, createBranch, createNeonApiFromOptions, createRealNeonApi, defineConfig, describeNativeFinding, enforceLimits, findUndeclaredNativePackages, inspect, isPartialBranchCreateError, isPlatformError, loadConfigFromFile, plan, pullConfig, pushConfig, traceNativePackages };

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

@@ -1,3 +1,4 @@
+import { NativeTraceDeps } from "./native-packages.js";
 import { ResolvedFunctionConfig } from "@neon/config";
 
 //#region src/lib/function-bundle.d.ts
@@ -11,6 +12,14 @@ import { ResolvedFunctionConfig } from "@neon/config";
  * into their bundle.
  */
 type FunctionBundler = (fn: ResolvedFunctionConfig) => Promise<Uint8Array>;
+/**
+ * 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`.
+ */
+declare 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.
  *
@@ -34,7 +43,18 @@ type FunctionBundler = (fn: ResolvedFunctionConfig) => Promise<Uint8Array>;
  * 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>;
+declare function buildFunctionBundle(fn: ResolvedFunctionConfig, options?: {
+  nativeDeps?: Partial<NativeTraceDeps>;
+  /**
+   * Where advisory findings go — the undeclared-native-dependency report, and a package
+   * whose version could not be pinned.
+   *
+   * Defaults to discarding them, because a library has no business writing to the
+   * console. Pass a handler: these are the only signal that a function will fail at
+   * invoke, and the CLI wires this to its logger for exactly that reason.
+   */
+  onWarning?: (message: string) => void;
+}): Promise<Uint8Array>;
 //#endregion
-export { FunctionBundler, buildFunctionBundle };
+export { ESM_CJS_INTEROP_BANNER, FunctionBundler, buildFunctionBundle };
 //# sourceMappingURL=function-bundle.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"function-bundle.d.ts","names":[],"sources":["../../src/lib/function-bundle.ts"],"mappings":";;;;;;AAeA;AAA2B;AACtB;AACQ;AAAR;AAAO;AAmCU,KArCV,eAAA,GAqC6B,CAAA,EAAA,EApCpC,sBAoCoC,EAAA,GAnCpC,OAmCoC,CAnC5B,UAmC4B,CAAA;AAAA;AACpC;AACM;AAAR;AAAO;;;;;;;;;;;;;;;;;;;iBAFY,mBAAA,KACjB,yBACF,QAAQ"}
+{"version":3,"file":"function-bundle.d.ts","names":[],"sources":["../../src/lib/function-bundle.ts"],"mappings":";;;;;;;AA0BA;AAA2B;AACtB;AACQ;AAAR;AAAO;AASC,KAXD,eAAA,GAWuB,CAAA,EAAA,EAV9B,sBAU8B,EAAA,GAT9B,OAS8B,CATtB,UASsB,CAAA;AA0BnC;AAAyC;AACpC;AAEkB;AAAR;AAWJ;AAAR;AAAO,cAxCG,sBAAA,GAwCH,mOAAA;;;;;;;;;;;;;;;;;;;;;;;;iBAdY,mBAAA,KACjB;eAEU,QAAQ;;;;;;;;;;IAWpB,QAAQ"}

package/dist/lib/function-bundle.js

@@ -1,5 +1,7 @@
-import { ErrorCode, PlatformError } from "@neon/config";
-import { basename } from "node:path";
+import { assertZipWithinLimits, enforceLimits, traceNativePackages } from "./native-packages.js";
+import { describeNativeFinding, findUndeclaredNativePackages } from "./native-detect.js";
+import { ErrorCode, PlatformError, packagesToStage } from "@neon/config";
+import { basename, dirname } from "node:path";
 //#region src/lib/function-bundle.ts
 /**
 * Prepended to the ESM bundle. Bundled dependencies are frequently CommonJS, but an ESM
@@ -32,8 +34,11 @@ const ESM_CJS_INTEROP_BANNER = "import{createRequire as ___cr}from'module';impor
 * 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) {
+async function buildFunctionBundle(fn, options = {}) {
 	const esbuild = await loadEsbuild();
+	const externalPackages = fn.externalPackages ?? [];
+	const staged = packagesToStage(externalPackages);
+	const onWarning = options.onWarning ?? (() => {});
 	let result;
 	try {
 		result = await esbuild.build({
@@ -45,7 +50,8 @@ async function buildFunctionBundle(fn) {
 			format: "esm",
 			platform: "node",
 			banner: { js: ESM_CJS_INTEROP_BANNER },
-			external: [...fn.externalPackages ?? []],
+			external: externalPackages.map((pkg) => pkg.name),
+			metafile: true,
 			logLevel: "silent"
 		});
 	} catch (cause) {
@@ -53,7 +59,24 @@ async function buildFunctionBundle(fn) {
 	}
 	const entries = {};
 	for (const file of result.outputFiles ?? []) entries[basename(file.path)] = file.contents;
-	return zipBundle(entries);
+	for (const finding of findUndeclaredNativePackages({
+		metafile: result.metafile,
+		declared: externalPackages.map((pkg) => pkg.name),
+		projectDir: dirname(fn.source)
+	})) onWarning(describeNativeFinding(fn.slug, finding));
+	if (staged.length === 0) return zipBundle(entries);
+	const traced = await traceNativePackages({
+		slug: fn.slug,
+		packages: staged,
+		projectDir: dirname(fn.source),
+		...options.nativeDeps ? { deps: options.nativeDeps } : {}
+	});
+	for (const warning of traced.warnings) onWarning(warning);
+	Object.assign(entries, traced.entries);
+	enforceLimits(fn.slug, entries);
+	const zip = await zipBundle(entries);
+	assertZipWithinLimits(fn.slug, zip, entries);
+	return zip;
 }
 async function zipBundle(entries) {
 	const { zipSync } = await loadFflate();
@@ -74,6 +97,6 @@ async function loadFflate() {
 	}
 }
 //#endregion
-export { buildFunctionBundle };
+export { ESM_CJS_INTEROP_BANNER, buildFunctionBundle };
 
 //# sourceMappingURL=function-bundle.js.map

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

@@ -1 +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\t// Packages the policy declared unbundleable (native addons, optional peers on\n\t\t\t// dead code paths). Their imports survive into the bundle and resolve against a\n\t\t\t// directory with no node_modules, so reaching one at runtime throws — which is\n\t\t\t// the documented contract of `FunctionDef.externalPackages`, not a bug here.\n\t\t\texternal: [...(fn.externalPackages ?? [])],\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;GAKrC,UAAU,CAAC,GAAI,GAAG,oBAAoB,CAAC,CAAE;GACzC,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"}
+{"version":3,"file":"function-bundle.js","names":[],"sources":["../../src/lib/function-bundle.ts"],"sourcesContent":["import { basename, dirname } from \"node:path\";\nimport {\n\tErrorCode,\n\tPlatformError,\n\tpackagesToStage,\n\ttype ResolvedFunctionConfig,\n} from \"@neon/config\";\nimport {\n\tdescribeNativeFinding,\n\tfindUndeclaredNativePackages,\n} from \"./native-detect.js\";\nimport {\n\tassertZipWithinLimits,\n\tenforceLimits,\n\ttype NativeTraceDeps,\n\ttraceNativePackages,\n} from \"./native-packages.js\";\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 */\nexport const 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\toptions: {\n\t\tnativeDeps?: Partial<NativeTraceDeps>;\n\t\t/**\n\t\t * Where advisory findings go — the undeclared-native-dependency report, and a package\n\t\t * whose version could not be pinned.\n\t\t *\n\t\t * Defaults to discarding them, because a library has no business writing to the\n\t\t * console. Pass a handler: these are the only signal that a function will fail at\n\t\t * invoke, and the CLI wires this to its logger for exactly that reason.\n\t\t */\n\t\tonWarning?: (message: string) => void;\n\t} = {},\n): Promise<Uint8Array> {\n\tconst esbuild = await loadEsbuild();\n\tconst externalPackages = fn.externalPackages ?? [];\n\tconst staged = packagesToStage(externalPackages);\n\tconst onWarning = options.onWarning ?? (() => {});\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\t// Packages the policy declared unbundleable. Their imports survive into the\n\t\t\t// bundle instead of being followed; whether they then resolve at runtime depends\n\t\t\t// on `includeFiles`, which is acted on below. Both modes are external here.\n\t\t\texternal: externalPackages.map((pkg) => pkg.name),\n\t\t\t// Reveals which packages were bundled in, so an undeclared native dependency can\n\t\t\t// be reported. Costs nothing here — esbuild is already running.\n\t\t\tmetafile: true,\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\t// Only reachable on a successful build, which is the point: `sharp` and its kind bundle\n\t// cleanly and fail at invoke, so this is exactly the case nothing else catches. A build\n\t// that throws has already failed loudly with esbuild's own diagnostic.\n\tfor (const finding of findUndeclaredNativePackages({\n\t\tmetafile: result.metafile,\n\t\tdeclared: externalPackages.map((pkg) => pkg.name),\n\t\tprojectDir: dirname(fn.source),\n\t})) {\n\t\tonWarning(describeNativeFinding(fn.slug, finding));\n\t}\n\n\t// The pre-existing path, byte for byte: no install, no trace, no size check, and an\n\t// archive of exactly the esbuild output. A policy that declares nothing to stage — or\n\t// sets `includeFiles: false` on everything — deploys the archive it always did.\n\tif (staged.length === 0) return zipBundle(entries);\n\n\tconst traced = await traceNativePackages({\n\t\tslug: fn.slug,\n\t\tpackages: staged,\n\t\t// The user's project, located from their entry — where their resolved versions are\n\t\t// read from. Only versions: the files themselves come from the staging install.\n\t\tprojectDir: dirname(fn.source),\n\t\t...(options.nativeDeps ? { deps: options.nativeDeps } : {}),\n\t});\n\tfor (const warning of traced.warnings) onWarning(warning);\n\t// Keys carry their `node_modules/...` path, so the archive reproduces the tree layout a\n\t// `.node` addon needs to find its sibling libraries. Do not flatten these.\n\tObject.assign(entries, traced.entries);\n\n\t// Re-checked against the final archive: the staged files were measured without the\n\t// bundle, so the entry count and uncompressed total are only complete now.\n\tenforceLimits(fn.slug, entries);\n\tconst zip = await zipBundle(entries);\n\tassertZipWithinLimits(fn.slug, zip, entries);\n\treturn zip;\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":";;;;;;;;;;;;AAqCA,MAAa,yBACZ;;;;;;;;;;;;;;;;;;;;;;;;AAyBD,eAAsB,oBACrB,IACA,UAWI,CAAC,GACiB;CACtB,MAAM,UAAU,MAAM,YAAY;CAClC,MAAM,mBAAmB,GAAG,oBAAoB,CAAC;CACjD,MAAM,SAAS,gBAAgB,gBAAgB;CAC/C,MAAM,YAAY,QAAQ,oBAAoB,CAAC;CAE/C,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;GAIrC,UAAU,iBAAiB,KAAK,QAAQ,IAAI,IAAI;GAGhD,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,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;CAMrC,KAAK,MAAM,WAAW,6BAA6B;EAClD,UAAU,OAAO;EACjB,UAAU,iBAAiB,KAAK,QAAQ,IAAI,IAAI;EAChD,YAAY,QAAQ,GAAG,MAAM;CAC9B,CAAC,GACA,UAAU,sBAAsB,GAAG,MAAM,OAAO,CAAC;CAMlD,IAAI,OAAO,WAAW,GAAG,OAAO,UAAU,OAAO;CAEjD,MAAM,SAAS,MAAM,oBAAoB;EACxC,MAAM,GAAG;EACT,UAAU;EAGV,YAAY,QAAQ,GAAG,MAAM;EAC7B,GAAI,QAAQ,aAAa,EAAE,MAAM,QAAQ,WAAW,IAAI,CAAC;CAC1D,CAAC;CACD,KAAK,MAAM,WAAW,OAAO,UAAU,UAAU,OAAO;CAGxD,OAAO,OAAO,SAAS,OAAO,OAAO;CAIrC,cAAc,GAAG,MAAM,OAAO;CAC9B,MAAM,MAAM,MAAM,UAAU,OAAO;CACnC,sBAAsB,GAAG,MAAM,KAAK,OAAO;CAC3C,OAAO;AACR;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/native-detect.d.ts

@@ -0,0 +1,64 @@
+//#region src/lib/native-detect.d.ts
+/**
+ * Why a package looks like it needs its files shipped. Carried through to the message so the
+ * report states the evidence rather than a prediction about what will happen at invoke.
+ */
+type NativeEvidence = {
+  kind: "binary";
+  file: string;
+} | {
+  kind: "platformDependency";
+  dependency: string;
+  file: string;
+} | {
+  kind: "buildsFromSource";
+  script: string;
+} | {
+  kind: "prebuiltManifest";
+};
+type NativeFinding = {
+  /** The package as it appears in the user's tree. */
+  name: string;
+  evidence: NativeEvidence;
+};
+/**
+ * The packages a bundle pulled in that carry native code and were not declared in
+ * `externalPackages`.
+ *
+ * **This is evidence, not a verdict.** It proves the package contains or depends on compiled
+ * code, never that this function's code path reaches it — a package with an optional native
+ * accelerator and a working JavaScript fallback (`ws` with `bufferutil`, a Prisma client with
+ * no Rust engine) looks identical from here and deploys fine today. So the caller reports it
+ * and continues; it must not fail a deploy.
+ *
+ * Only reachable after a successful build. A package esbuild could not resolve, or a `.node`
+ * it has no loader for, throws before any metafile exists — those already fail loudly with
+ * esbuild's own diagnostic.
+ */
+declare function findUndeclaredNativePackages(options: {
+  metafile: {
+    inputs?: Record<string, unknown>;
+  } | undefined;
+  declared: readonly string[];
+  projectDir: string;
+  /** What metafile input paths are relative to. Defaults to the process working directory. */
+  cwd?: string;
+}): NativeFinding[];
+/**
+ * The package an esbuild metafile input belongs to, or `undefined` for the user's own source.
+ *
+ * Keyed off the **last** `node_modules/` segment, which is what makes pnpm's
+ * `node_modules/.pnpm/sharp@0.35.3/node_modules/sharp/lib/x.js` resolve to `sharp` rather
+ * than `.pnpm`. Yarn PnP resolves out of zip archives with no `node_modules` segment at all
+ * and yields nothing here, which is the safe direction: a missed package is a missing
+ * warning, not a wrong one.
+ */
+declare function packageNameFromInput(input: string): string | undefined;
+/**
+ * The report a user sees. States what was found and both ways to act on it, with the
+ * shipping form first because it is the one that produces a working function.
+ */
+declare function describeNativeFinding(slug: string, finding: NativeFinding): string;
+//#endregion
+export { NativeEvidence, NativeFinding, describeNativeFinding, findUndeclaredNativePackages, packageNameFromInput };
+//# sourceMappingURL=native-detect.d.ts.map

package/dist/lib/native-detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-detect.d.ts","names":[],"sources":["../../src/lib/native-detect.ts"],"mappings":";;AAUA;AAMA;AAwCA;AAA4C,KA9ChC,cAAA,GA8CgC;EACtB,IAAA,EAAA,QAAA;EAKlB,IAAA,EAAA,MAAA;AAAa,CAAA,GAAA;EA2ED,IAAA,EAAA,oBAAoB;EAyIpB,UAAA,EAAA,MAAA;;;;;;;;KAlQJ,aAAA;;;YAGD;;;;;;;;;;;;;;;;iBAqCK,4BAAA;;aACM;;;;;;IAKlB;;;;;;;;;;iBA2EY,oBAAA;;;;;iBAyIA,qBAAA,wBAEN"}

package/dist/lib/native-detect.js

@@ -0,0 +1,202 @@
+import { findPackageDir, readPackageManifest } from "./resolve-package.js";
+import { RUNTIME_TARGET, RUNTIME_TARGET_LABEL } from "./native-packages.js";
+import { externalPackageRoot } from "@neon/config";
+import { isAbsolute, join, resolve } from "node:path";
+import { readdirSync, realpathSync } from "node:fs";
+//#region src/lib/native-detect.ts
+/** Depth of the walk for a `.node`/`.so` inside one package. */
+const SCAN_DEPTH = 4;
+const BINARY_PATTERN = /\.(node|so)(\.\d+)*$/;
+const GYP_PATTERN = /\b(node-gyp|node-pre-gyp|prebuild-install|cmake-js)\b/;
+/**
+* The packages a bundle pulled in that carry native code and were not declared in
+* `externalPackages`.
+*
+* **This is evidence, not a verdict.** It proves the package contains or depends on compiled
+* code, never that this function's code path reaches it — a package with an optional native
+* accelerator and a working JavaScript fallback (`ws` with `bufferutil`, a Prisma client with
+* no Rust engine) looks identical from here and deploys fine today. So the caller reports it
+* and continues; it must not fail a deploy.
+*
+* Only reachable after a successful build. A package esbuild could not resolve, or a `.node`
+* it has no loader for, throws before any metafile exists — those already fail loudly with
+* esbuild's own diagnostic.
+*/
+function findUndeclaredNativePackages(options) {
+	const { metafile, declared, projectDir } = options;
+	const cwd = options.cwd ?? process.cwd();
+	const inputs = metafile?.inputs;
+	if (!inputs) return [];
+	const declaredRoots = new Set(declared.map(externalPackageRoot));
+	const findings = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const input of Object.keys(inputs)) {
+		const located = packageFromInput(input, cwd);
+		if (located === void 0) continue;
+		const { name } = located;
+		if (declaredRoots.has(name)) continue;
+		const dir = located.dir ?? findPackageDir(projectDir, name);
+		if (dir === void 0 || seen.has(dir)) continue;
+		seen.add(dir);
+		const evidence = nativeEvidence(dir, projectDir);
+		if (evidence !== void 0) findings.push({
+			name,
+			evidence
+		});
+	}
+	return findings;
+}
+/**
+* The package an input belongs to, and where that exact copy lives on disk.
+*
+* Taking the directory straight from the input path rather than searching for the name is
+* what makes this correct under pnpm, whose transitive dependencies are not linked at the
+* project root at all and whose store holds several versions of the same package side by
+* side. A search from the project root would miss the first and could inspect the wrong copy
+* in the second.
+*/
+function packageFromInput(input, cwd) {
+	const name = packageNameFromInput(input);
+	if (name === void 0) return void 0;
+	const normalized = input.split("\\").join("/");
+	const prefixLength = normalized.lastIndexOf("node_modules/") + 13 + name.length;
+	const relativeDir = normalized.slice(0, prefixLength);
+	if (!relativeDir.endsWith(name)) return { name };
+	const absolute = isAbsolute(relativeDir) ? relativeDir : resolve(cwd, relativeDir);
+	try {
+		return {
+			name,
+			dir: realpathSync(absolute)
+		};
+	} catch {
+		return { name };
+	}
+}
+/**
+* The package an esbuild metafile input belongs to, or `undefined` for the user's own source.
+*
+* Keyed off the **last** `node_modules/` segment, which is what makes pnpm's
+* `node_modules/.pnpm/sharp@0.35.3/node_modules/sharp/lib/x.js` resolve to `sharp` rather
+* than `.pnpm`. Yarn PnP resolves out of zip archives with no `node_modules` segment at all
+* and yields nothing here, which is the safe direction: a missed package is a missing
+* warning, not a wrong one.
+*/
+function packageNameFromInput(input) {
+	const normalized = input.split("\\").join("/");
+	const last = normalized.lastIndexOf("node_modules/");
+	if (last === -1) return void 0;
+	const segments = normalized.slice(last + 13).split("/").filter((segment) => segment.length > 0);
+	if (segments.length === 0) return void 0;
+	if (segments[0].startsWith("@")) return segments.length >= 2 ? `${segments[0]}/${segments[1]}` : void 0;
+	return segments[0];
+}
+const readManifest = (dir) => readPackageManifest(dir);
+/**
+* A manifest field npm accepts as either a string or an array of strings, narrowed to a list.
+* Anything else is treated as absent: this is an advisory scan reading arbitrary third-party
+* manifests, and a malformed field must not take a deploy down.
+*/
+function stringList(value) {
+	if (typeof value === "string") return [value];
+	if (!Array.isArray(value)) return void 0;
+	const entries = value.filter((entry) => typeof entry === "string");
+	return entries.length === value.length ? entries : void 0;
+}
+function optionalDependencies(manifest) {
+	const value = manifest.optionalDependencies;
+	return typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
+}
+/**
+* Whether a manifest's own `os`/`cpu`/`libc` fields permit the Functions runtime. A package
+* that excludes it — `fsevents` is darwin-only, a musl-only build cannot load on glibc —
+* cannot run there whatever we do, so it is not a candidate for shipping and reporting it
+* would be noise.
+*/
+function runsOnRuntime(manifest) {
+	const permits = (raw, value) => {
+		const field = stringList(raw);
+		if (field === void 0 || field.length === 0) return true;
+		if (field.some((entry) => entry === `!${value}`)) return false;
+		const positives = field.filter((entry) => !entry.startsWith("!"));
+		return positives.length === 0 || positives.includes(value);
+	};
+	return permits(manifest.os, RUNTIME_TARGET.os) && permits(manifest.cpu, RUNTIME_TARGET.cpu) && permits(manifest.libc, RUNTIME_TARGET.libc);
+}
+/** The first native signal a package shows, or `undefined` if it looks like plain JavaScript. */
+function nativeEvidence(dir, projectDir) {
+	const manifest = readManifest(dir);
+	if (manifest === void 0) return void 0;
+	if (!runsOnRuntime(manifest)) return void 0;
+	const own = findBinary(dir, SCAN_DEPTH);
+	if (own !== void 0) return {
+		kind: "binary",
+		file: own
+	};
+	for (const dependency of Object.keys(optionalDependencies(manifest))) {
+		const dependencyDir = findPackageDir(dir, dependency) ?? findPackageDir(projectDir, dependency);
+		if (dependencyDir === void 0) continue;
+		const dependencyManifest = readManifest(dependencyDir);
+		if (dependencyManifest === void 0) continue;
+		if (!(stringList(dependencyManifest.os) !== void 0 || stringList(dependencyManifest.cpu) !== void 0 || stringList(dependencyManifest.libc) !== void 0)) continue;
+		const file = findBinary(dependencyDir, SCAN_DEPTH);
+		if (file !== void 0) return {
+			kind: "platformDependency",
+			dependency,
+			file
+		};
+	}
+	const scripts = manifest.scripts;
+	const script = typeof scripts?.install === "string" ? scripts.install : typeof scripts?.postinstall === "string" ? scripts.postinstall : void 0;
+	if (script !== void 0 && GYP_PATTERN.test(script)) return {
+		kind: "buildsFromSource",
+		script
+	};
+	if (manifest.binary !== void 0) return { kind: "prebuiltManifest" };
+}
+/** First compiled artifact under `dir`, not descending into a nested `node_modules`. */
+function findBinary(dir, depth) {
+	if (depth < 0) return void 0;
+	let listing;
+	try {
+		listing = readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return;
+	}
+	for (const entry of listing) if (entry.isFile() && BINARY_PATTERN.test(entry.name)) return entry.name;
+	for (const entry of listing) {
+		if (!entry.isDirectory() || entry.name === "node_modules") continue;
+		const found = findBinary(join(dir, entry.name), depth - 1);
+		if (found !== void 0) return join(entry.name, found);
+	}
+}
+/**
+* The report a user sees. States what was found and both ways to act on it, with the
+* shipping form first because it is the one that produces a working function.
+*/
+function describeNativeFinding(slug, finding) {
+	const { name, evidence } = finding;
+	return [
+		`Function "${slug}" bundles "${name}", and ${(() => {
+			switch (evidence.kind) {
+				case "binary": return `it contains a compiled binary (${evidence.file} on this machine; the deploy needs the ${RUNTIME_TARGET_LABEL} build)`;
+				case "platformDependency": return `it loads a compiled binary from ${evidence.dependency} (${evidence.file} on this machine; the deploy needs the ${RUNTIME_TARGET_LABEL} build)`;
+				case "buildsFromSource": return `it compiles a binary at install time (${evidence.script})`;
+				case "prebuiltManifest": return "its manifest declares a prebuilt binary";
+			}
+		})()}.`,
+		`A compiled binary cannot be bundled, so if this function evaluates that import it`,
+		`fails at invoke rather than at deploy.`,
+		"",
+		`  Ship its files with the deploy:`,
+		`      externalPackages: ["${name}"]`,
+		"",
+		`If "${name}" is only reached behind a working JavaScript fallback, this deploy is`,
+		`already correct and needs no change — this is advisory and never fails a deploy.`,
+		`Do not add includeFiles: false to silence it: that externalizes "${name}" and ships`,
+		`nothing for it, so a top-level import of it would then fail on every invoke.`
+	].join("\n");
+}
+//#endregion
+export { describeNativeFinding, findUndeclaredNativePackages, packageNameFromInput };
+
+//# sourceMappingURL=native-detect.js.map

package/dist/lib/native-detect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-detect.js","names":[],"sources":["../../src/lib/native-detect.ts"],"sourcesContent":["import { type Dirent, readdirSync, realpathSync } from \"node:fs\";\nimport { isAbsolute, join, resolve } from \"node:path\";\nimport { externalPackageRoot } from \"@neon/config\";\nimport { RUNTIME_TARGET, RUNTIME_TARGET_LABEL } from \"./native-packages.js\";\nimport { findPackageDir, readPackageManifest } from \"./resolve-package.js\";\n\n/**\n * Why a package looks like it needs its files shipped. Carried through to the message so the\n * report states the evidence rather than a prediction about what will happen at invoke.\n */\nexport type NativeEvidence =\n\t| { kind: \"binary\"; file: string }\n\t| { kind: \"platformDependency\"; dependency: string; file: string }\n\t| { kind: \"buildsFromSource\"; script: string }\n\t| { kind: \"prebuiltManifest\" };\n\nexport type NativeFinding = {\n\t/** The package as it appears in the user's tree. */\n\tname: string;\n\tevidence: NativeEvidence;\n};\n\n/** Depth of the walk for a `.node`/`.so` inside one package. */\nconst SCAN_DEPTH = 4;\n\nconst BINARY_PATTERN = /\\.(node|so)(\\.\\d+)*$/;\n\nconst GYP_PATTERN = /\\b(node-gyp|node-pre-gyp|prebuild-install|cmake-js)\\b/;\n\n/**\n * Third-party manifests are arbitrary JSON, so every field is `unknown` and narrowed at use.\n * npm accepts `os`/`cpu`/`libc` as a bare string as well as an array.\n */\ntype Manifest = {\n\tos?: unknown;\n\tcpu?: unknown;\n\tlibc?: unknown;\n\tbinary?: unknown;\n\toptionalDependencies?: unknown;\n\tscripts?: Record<string, unknown>;\n};\n\n/**\n * The packages a bundle pulled in that carry native code and were not declared in\n * `externalPackages`.\n *\n * **This is evidence, not a verdict.** It proves the package contains or depends on compiled\n * code, never that this function's code path reaches it — a package with an optional native\n * accelerator and a working JavaScript fallback (`ws` with `bufferutil`, a Prisma client with\n * no Rust engine) looks identical from here and deploys fine today. So the caller reports it\n * and continues; it must not fail a deploy.\n *\n * Only reachable after a successful build. A package esbuild could not resolve, or a `.node`\n * it has no loader for, throws before any metafile exists — those already fail loudly with\n * esbuild's own diagnostic.\n */\nexport function findUndeclaredNativePackages(options: {\n\tmetafile: { inputs?: Record<string, unknown> } | undefined;\n\tdeclared: readonly string[];\n\tprojectDir: string;\n\t/** What metafile input paths are relative to. Defaults to the process working directory. */\n\tcwd?: string;\n}): NativeFinding[] {\n\tconst { metafile, declared, projectDir } = options;\n\tconst cwd = options.cwd ?? process.cwd();\n\tconst inputs = metafile?.inputs;\n\tif (!inputs) return [];\n\n\t// A declared subpath covers its whole package: esbuild externalizing `pkg` externalizes\n\t// `pkg/sub` with it, so the package is spoken for either way.\n\tconst declaredRoots = new Set(declared.map(externalPackageRoot));\n\n\tconst findings: NativeFinding[] = [];\n\tconst seen = new Set<string>();\n\tfor (const input of Object.keys(inputs)) {\n\t\tconst located = packageFromInput(input, cwd);\n\t\tif (located === undefined) continue;\n\t\tconst { name } = located;\n\t\tif (declaredRoots.has(name)) continue;\n\n\t\t// Keyed by directory, not name: pnpm and nested installs can put two versions of one\n\t\t// package in a graph, and they are genuinely different packages to inspect.\n\t\tconst dir = located.dir ?? findPackageDir(projectDir, name);\n\t\tif (dir === undefined || seen.has(dir)) continue;\n\t\tseen.add(dir);\n\n\t\tconst evidence = nativeEvidence(dir, projectDir);\n\t\tif (evidence !== undefined) findings.push({ name, evidence });\n\t}\n\treturn findings;\n}\n\n/**\n * The package an input belongs to, and where that exact copy lives on disk.\n *\n * Taking the directory straight from the input path rather than searching for the name is\n * what makes this correct under pnpm, whose transitive dependencies are not linked at the\n * project root at all and whose store holds several versions of the same package side by\n * side. A search from the project root would miss the first and could inspect the wrong copy\n * in the second.\n */\nfunction packageFromInput(\n\tinput: string,\n\tcwd: string,\n): { name: string; dir?: string } | undefined {\n\tconst name = packageNameFromInput(input);\n\tif (name === undefined) return undefined;\n\n\tconst normalized = input.split(\"\\\\\").join(\"/\");\n\tconst marker = \"node_modules/\";\n\tconst last = normalized.lastIndexOf(marker);\n\t// The path through the end of the package's own segments is its directory.\n\tconst prefixLength = last + marker.length + name.length;\n\tconst relativeDir = normalized.slice(0, prefixLength);\n\tif (!relativeDir.endsWith(name)) return { name };\n\n\tconst absolute = isAbsolute(relativeDir)\n\t\t? relativeDir\n\t\t: resolve(cwd, relativeDir);\n\ttry {\n\t\t// realpath so a pnpm symlink and its store target dedupe to one physical package.\n\t\treturn { name, dir: realpathSync(absolute) };\n\t} catch {\n\t\t// The path esbuild reported is not readable from here — fall back to a search.\n\t\treturn { name };\n\t}\n}\n\n/**\n * The package an esbuild metafile input belongs to, or `undefined` for the user's own source.\n *\n * Keyed off the **last** `node_modules/` segment, which is what makes pnpm's\n * `node_modules/.pnpm/sharp@0.35.3/node_modules/sharp/lib/x.js` resolve to `sharp` rather\n * than `.pnpm`. Yarn PnP resolves out of zip archives with no `node_modules` segment at all\n * and yields nothing here, which is the safe direction: a missed package is a missing\n * warning, not a wrong one.\n */\nexport function packageNameFromInput(input: string): string | undefined {\n\tconst normalized = input.split(\"\\\\\").join(\"/\");\n\tconst marker = \"node_modules/\";\n\tconst last = normalized.lastIndexOf(marker);\n\tif (last === -1) return undefined;\n\n\tconst rest = normalized.slice(last + marker.length);\n\tconst segments = rest.split(\"/\").filter((segment) => segment.length > 0);\n\tif (segments.length === 0) return undefined;\n\tif (segments[0].startsWith(\"@\")) {\n\t\treturn segments.length >= 2\n\t\t\t? `${segments[0]}/${segments[1]}`\n\t\t\t: undefined;\n\t}\n\treturn segments[0];\n}\n\nconst readManifest = (dir: string): Manifest | undefined =>\n\treadPackageManifest(dir) as Manifest | undefined;\n\n/**\n * A manifest field npm accepts as either a string or an array of strings, narrowed to a list.\n * Anything else is treated as absent: this is an advisory scan reading arbitrary third-party\n * manifests, and a malformed field must not take a deploy down.\n */\nfunction stringList(value: unknown): string[] | undefined {\n\tif (typeof value === \"string\") return [value];\n\tif (!Array.isArray(value)) return undefined;\n\tconst entries = value.filter(\n\t\t(entry): entry is string => typeof entry === \"string\",\n\t);\n\treturn entries.length === value.length ? entries : undefined;\n}\n\nfunction optionalDependencies(manifest: Manifest): Record<string, unknown> {\n\tconst value = manifest.optionalDependencies;\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value)\n\t\t? (value as Record<string, unknown>)\n\t\t: {};\n}\n\n/**\n * Whether a manifest's own `os`/`cpu`/`libc` fields permit the Functions runtime. A package\n * that excludes it — `fsevents` is darwin-only, a musl-only build cannot load on glibc —\n * cannot run there whatever we do, so it is not a candidate for shipping and reporting it\n * would be noise.\n */\nfunction runsOnRuntime(manifest: Manifest): boolean {\n\tconst permits = (raw: unknown, value: string): boolean => {\n\t\tconst field = stringList(raw);\n\t\tif (field === undefined || field.length === 0) return true;\n\t\tif (field.some((entry) => entry === `!${value}`)) return false;\n\t\tconst positives = field.filter((entry) => !entry.startsWith(\"!\"));\n\t\treturn positives.length === 0 || positives.includes(value);\n\t};\n\treturn (\n\t\tpermits(manifest.os, RUNTIME_TARGET.os) &&\n\t\tpermits(manifest.cpu, RUNTIME_TARGET.cpu) &&\n\t\tpermits(manifest.libc, RUNTIME_TARGET.libc)\n\t);\n}\n\n/** The first native signal a package shows, or `undefined` if it looks like plain JavaScript. */\nfunction nativeEvidence(\n\tdir: string,\n\tprojectDir: string,\n): NativeEvidence | undefined {\n\tconst manifest = readManifest(dir);\n\tif (manifest === undefined) return undefined;\n\tif (!runsOnRuntime(manifest)) return undefined;\n\n\tconst own = findBinary(dir, SCAN_DEPTH);\n\tif (own !== undefined) return { kind: \"binary\", file: own };\n\n\t// The modern prebuilt pattern: the parent is pure JavaScript and the binary lives in a\n\t// platform-gated optional dependency, which is why scanning only the parent misses it.\n\tfor (const dependency of Object.keys(optionalDependencies(manifest))) {\n\t\t// Search from the package's own directory first so a nested or pnpm-linked copy wins\n\t\t// over an unrelated one at the project root, then fall back to the project.\n\t\tconst dependencyDir =\n\t\t\tfindPackageDir(dir, dependency) ??\n\t\t\tfindPackageDir(projectDir, dependency);\n\t\tif (dependencyDir === undefined) continue;\n\t\tconst dependencyManifest = readManifest(dependencyDir);\n\t\tif (dependencyManifest === undefined) continue;\n\t\t// The sibling built for *this* host is the one installed locally; its os/cpu fields\n\t\t// are what mark the package as platform-gated at all.\n\t\tconst platformGated =\n\t\t\tstringList(dependencyManifest.os) !== undefined ||\n\t\t\tstringList(dependencyManifest.cpu) !== undefined ||\n\t\t\tstringList(dependencyManifest.libc) !== undefined;\n\t\tif (!platformGated) continue;\n\t\tconst file = findBinary(dependencyDir, SCAN_DEPTH);\n\t\tif (file !== undefined)\n\t\t\treturn { kind: \"platformDependency\", dependency, file };\n\t}\n\n\tconst scripts = manifest.scripts;\n\tconst script =\n\t\ttypeof scripts?.install === \"string\"\n\t\t\t? scripts.install\n\t\t\t: typeof scripts?.postinstall === \"string\"\n\t\t\t\t? scripts.postinstall\n\t\t\t\t: undefined;\n\tif (script !== undefined && GYP_PATTERN.test(script))\n\t\treturn { kind: \"buildsFromSource\", script };\n\n\tif (manifest.binary !== undefined) return { kind: \"prebuiltManifest\" };\n\n\treturn undefined;\n}\n\n/** First compiled artifact under `dir`, not descending into a nested `node_modules`. */\nfunction findBinary(dir: string, depth: number): string | undefined {\n\tif (depth < 0) return undefined;\n\tlet listing: Dirent[];\n\ttry {\n\t\tlisting = readdirSync(dir, { withFileTypes: true });\n\t} catch {\n\t\treturn undefined;\n\t}\n\tfor (const entry of listing) {\n\t\tif (entry.isFile() && BINARY_PATTERN.test(entry.name))\n\t\t\treturn entry.name;\n\t}\n\tfor (const entry of listing) {\n\t\tif (!entry.isDirectory() || entry.name === \"node_modules\") continue;\n\t\tconst found = findBinary(join(dir, entry.name), depth - 1);\n\t\tif (found !== undefined) return join(entry.name, found);\n\t}\n\treturn undefined;\n}\n\n/**\n * The report a user sees. States what was found and both ways to act on it, with the\n * shipping form first because it is the one that produces a working function.\n */\nexport function describeNativeFinding(\n\tslug: string,\n\tfinding: NativeFinding,\n): string {\n\tconst { name, evidence } = finding;\n\t// The evidence comes from the tree on *this* machine, so it names the host's build. Said\n\t// out loud, because otherwise a linux-arm64 deploy reporting a darwin binary reads as a\n\t// bug in the tool rather than as a description of the developer's own node_modules.\n\tconst because = (() => {\n\t\tswitch (evidence.kind) {\n\t\t\tcase \"binary\":\n\t\t\t\treturn `it contains a compiled binary (${evidence.file} on this machine; the deploy needs the ${RUNTIME_TARGET_LABEL} build)`;\n\t\t\tcase \"platformDependency\":\n\t\t\t\treturn `it loads a compiled binary from ${evidence.dependency} (${evidence.file} on this machine; the deploy needs the ${RUNTIME_TARGET_LABEL} build)`;\n\t\t\tcase \"buildsFromSource\":\n\t\t\t\treturn `it compiles a binary at install time (${evidence.script})`;\n\t\t\tcase \"prebuiltManifest\":\n\t\t\t\treturn \"its manifest declares a prebuilt binary\";\n\t\t}\n\t})();\n\n\treturn [\n\t\t`Function \"${slug}\" bundles \"${name}\", and ${because}.`,\n\t\t`A compiled binary cannot be bundled, so if this function evaluates that import it`,\n\t\t`fails at invoke rather than at deploy.`,\n\t\t\"\",\n\t\t`  Ship its files with the deploy:`,\n\t\t`      externalPackages: [\"${name}\"]`,\n\t\t\"\",\n\t\t`If \"${name}\" is only reached behind a working JavaScript fallback, this deploy is`,\n\t\t`already correct and needs no change — this is advisory and never fails a deploy.`,\n\t\t`Do not add includeFiles: false to silence it: that externalizes \"${name}\" and ships`,\n\t\t`nothing for it, so a top-level import of it would then fail on every invoke.`,\n\t].join(\"\\n\");\n}\n"],"mappings":"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"}

package/dist/lib/native-packages.d.ts

@@ -0,0 +1,108 @@
+//#region src/lib/native-packages.d.ts
+/**
+ * The architecture, OS and libc a Neon Function runs on. Native packages are installed for
+ * this triple rather than for the machine running the deploy, which is usually a macOS or
+ * linux-x64 laptop.
+ */
+declare const RUNTIME_TARGET: {
+  readonly cpu: "arm64";
+  readonly os: "linux";
+  readonly libc: "glibc";
+};
+/** Human-readable form of {@link RUNTIME_TARGET}, for error messages. */
+declare const RUNTIME_TARGET_LABEL: string;
+/**
+ * Size ceilings the deploy must respect. The build service rejects an archive over these,
+ * with an error that surfaces long after the CLI has exited, so they are checked here where
+ * the message can name the files responsible.
+ *
+ * These mirror the service's limits rather than defining them. Passing them in lets a caller
+ * track a change on the service side without editing this module.
+ */
+type ArchiveLimits = {
+  /** Compressed archive bytes — the ZIP that is uploaded. */
+  maxZipBytes: number;
+  /** Total uncompressed bytes across every archive entry. */
+  maxTotalBytes: number;
+  /** Number of archive entries. */
+  maxEntries: number;
+};
+declare const DEFAULT_ARCHIVE_LIMITS: ArchiveLimits;
+/** Injectable side effects, so the tracing logic is testable without a registry or npm. */
+type NativeTraceDeps = {
+  /** Install `specs` for the runtime target into `cwd`. Resolves on success. */
+  install: (cwd: string, specs: string[]) => Promise<void>;
+  /** Trace `entry` within `base`, returning archive-relative file paths. */
+  /**
+   * Trace `entry` within `base`.
+   *
+   * `files` are archive-relative paths. `unresolved` are the specifiers the tracer could
+   * not follow, which are classified rather than reported wholesale — see
+   * {@link concreteUnresolved}.
+   */
+  trace: (base: string, entry: string) => Promise<{
+    files: string[];
+    unresolved?: string[];
+  }>;
+  /** Version of `pkg` as resolved in the user's project, or undefined if not installed. */
+  installedVersion: (projectDir: string, pkg: string) => string | undefined;
+};
+/** Files to place in the archive under `node_modules/`, keyed by archive-relative path. */
+type NativeTraceResult = {
+  entries: Record<string, Uint8Array>;
+  /**
+   * Advisory findings from the staging run — currently a relative import the tracer could
+   * not resolve, meaning that file will not be in the archive.
+   *
+   * The caller must surface these. They are advisory rather than fatal because the tracer
+   * cannot tell a required import from one wrapped in a try/catch, but an unreported one is
+   * a function that deploys clean and fails at invoke.
+   */
+  warnings: string[];
+};
+/**
+ * Collect the files the declared native packages need, ready to be merged into the archive.
+ *
+ * Three steps, in this order for reasons that are not interchangeable:
+ *
+ * 1. **Install for the runtime target into a throwaway directory.** The user's own
+ *    `node_modules` is never read for these files. Its binaries are built for their machine,
+ *    and a cross-platform install is not sticky — a later plain `npm install` re-resolves
+ *    optional dependencies for the host and replaces the target's packages with the host's.
+ *    Only the resolved *version* of the declared package is taken from the user's tree. That
+ *    is not the same as honouring their lockfile: transitive pins, overrides, patches, and
+ *    aliases are not carried across, so the staged graph can differ below the root.
+ * 2. **Trace the installed tree.** The file set cannot be discovered by asking Node:
+ *    `@img/sharp-linux-arm64` exports only `./sharp.node` and `./package`, with no `.` and no
+ *    wildcard, so its directory is unreachable through the resolver. A tracer that follows
+ *    `createRequire` is required — which is also why esbuild cannot see these files, and why
+ *    `sharp` bundles cleanly today and then fails at invoke.
+ * 3. **Copy the traced files, preserving the `node_modules` layout.** A `.node` addon locates
+ *    its sibling shared libraries by a path relative to its own directory, so flattening the
+ *    tree breaks loading even though every file is present.
+ */
+declare function traceNativePackages(options: {
+  slug: string;
+  packages: readonly string[];
+  projectDir: string;
+  limits?: ArchiveLimits;
+  deps?: Partial<NativeTraceDeps>;
+}): Promise<NativeTraceResult>;
+/**
+ * Check the archive against the build service's limits, naming the largest contributors. The
+ * compressed size is not known until the archive is zipped, so only the counts and
+ * uncompressed total are checked here; {@link assertZipWithinLimits} covers the rest.
+ *
+ * Exported so the caller can re-check the **final** archive: these entries are the staged
+ * files alone, and the bundle is merged in afterwards.
+ */
+declare function enforceLimits(slug: string, entries: Record<string, Uint8Array>, limits?: ArchiveLimits): void;
+/**
+ * Check the compressed archive, which is only measurable once it exists. Separate from
+ * {@link enforceLimits} for that reason, and exported so the bundler can call it on the
+ * finished ZIP.
+ */
+declare function assertZipWithinLimits(slug: string, zip: Uint8Array, entries: Record<string, Uint8Array>, limits?: ArchiveLimits): void;
+//#endregion
+export { ArchiveLimits, DEFAULT_ARCHIVE_LIMITS, NativeTraceDeps, NativeTraceResult, RUNTIME_TARGET, RUNTIME_TARGET_LABEL, assertZipWithinLimits, enforceLimits, traceNativePackages };
+//# sourceMappingURL=native-packages.d.ts.map

package/dist/lib/native-packages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-packages.d.ts","names":[],"sources":["../../src/lib/native-packages.ts"],"mappings":";;AAqBA;AAOA;AAwLA;AASA;AAOY,cA/MC,cA+Mc,EAAA;EAAA,SAAA,GAAA,EAAA,OAAA;EAEiB,SAAA,EAAA,EAAA,OAAA;EAYtC,SAAA,IAAA,EAAA,OAAA;AAAO,CAAA;AAMb;AAA6B,cA5NhB,oBA4NgB,EAAA,MAAA;AACJ;AAAf;AAAM;AA0ChB;AAAyC;AAI/B;AACM;AAAR;AACI,KArFA,aAAA,GAqFA;EAAR;EAAO,WAAA,EAAA,MAAA;EAwRK;EAAa,aAAA,EAAA,MAAA;EAEJ;EAAf,UAAA,EAAA,MAAA;AACD,CAAA;AAAsC,cAvWlC,sBAuWkC,EAvWV,aAuWU;AAyB/C;AAAqC,KAzXzB,eAAA,GAyXyB;EAE/B;EACmB,OAAA,EAAA,CAAA,GAAA,EAAA,MAAA,EAAA,KAAA,EAAA,MAAA,EAAA,EAAA,GA1XmB,OA0XnB,CAAA,IAAA,CAAA;EAAf;EACD;AAAsC;;;;;;0CA/WzC;;;;;;;;KAMM,iBAAA;WACF,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA0CH,mBAAA;;;;WAIZ;SACF,QAAQ;IACZ,QAAQ;;;;;;;;;iBAwRI,aAAA,wBAEN,eAAe,sBAChB;;;;;;iBAyBO,qBAAA,oBAEV,qBACI,eAAe,sBAChB"}