neon 8.10.3 → 8.11.1

package/README.md

@@ -1091,6 +1091,28 @@ neon snapshots schedule set --branch main --schedule '[{"frequency":"weekly","da
 
 All sub-commands honor the [global options](#global-options), including `--output json|yaml|table`.
 
+## Function templates (`functions new`)
+
+`neon functions new <template>` fetches a template from the Neon Function Registry, writes its modules into `functions/<slug>/` next to `neon.ts`, and declares the result in `neon.ts` (creating it when missing), the same way `config add function` does.
+
+```bash
+neon functions templates list
+neon functions new
+neon functions new basic
+neon functions new basic --slug hello --no-add-to-config
+neon functions new <template> --operation <id> --operation <id> --install
+```
+
+Without a template, a terminal asks which one to use; anything else exits with the available IDs. Like `bootstrap`, it asks once whether to install the template's dependencies (plus `@neon/config` and `@neon/env` when it creates `neon.ts`): `--yes` installs, `--no-install` skips, and a run without a terminal leaves the install command under `Next:`.
+
+A template's `layout` decides what you get. `router` writes one module per operation plus a generated `index.ts` that dispatches on the URL path, and declares one function. `separate` declares each operation as its own function under the slug the template gives it. Without `--operation` or `--all-operations`, a TTY asks which operations to include and anything else uses the template's recommended ones.
+
+Variables a template needs are declared on each function in `neon.ts` (`env: { API_KEY: process.env.API_KEY! }`) and added, without values, to `.env.example` next to it. Values are never written to `.env` or `.env.local` for you: a blank placeholder there would deploy as an empty string and delete the live value. Put the real value in the file `env pull` uses and deploy with `neon config apply --env .env.local`. `neon dev` reads function env from your shell, so export it there as well.
+
+Nothing is written until every check passes: a file that already exists with different contents needs `--force`, and a slug `neon.ts` already declares needs `--slug`, `--force`, or `--no-add-to-config`. A `separate` template sets its own slugs, so `--slug` only changes its directory; remove the existing declarations from `neon.ts`, or use `--force` or `--no-add-to-config`.
+
+The registry lives in [`registry/`](https://github.com/neondatabase/examples/tree/main/registry) in `neondatabase/examples`. The CLI reads the index from `https://neon.com/functions/registry/registry.json`, which serves `main` through a CDN cache, and falls back to raw GitHub when neon.com is unreachable. Template files are always read from raw GitHub. Set `NEON_FUNCTION_REGISTRY_DIR` to a local checkout to try templates before they are merged, or `NEON_FUNCTION_REGISTRY_URL` to read an index from somewhere else.
+
 ## Function triggers (`triggers`)
 
 `neon triggers` (alias `neon trigger`) manages Function triggers on a branch. Types are `schedule` (a five-field UTC cron expression) and `storage_object_created` (an object-storage bucket, with an optional object-key prefix).

package/dist/commands/auth.js

@@ -6,7 +6,7 @@ import { withExclusiveLock } from "../refresh_lock.js";
 import { getApiClient, isNeonApiError } from "../api.js";
 import { setAuthContext } from "../auth_context.js";
 import { a as isOwnedCredentialPath } from "../_chunks/paths-DMq0Lt7a.js";
-import { currentContextFile, isAskCommand, isClaimCommand, isConfigAdd, isConfigInit, isCurrentBranchProbe, isDocsCommand, isFeedbackCommand, isGitLocalCommand, isInspectDbUrl, isMcpCommand, isMcpOauth, isPluginsCommand, isProfileCommand, isSkillsCommand, isUnfollowedGitHookSync, readContextFile } from "../context.js";
+import { currentContextFile, isAskCommand, isClaimCommand, isConfigAdd, isConfigInit, isCurrentBranchProbe, isDocsCommand, isFeedbackCommand, isFunctionsTemplateCommand, isGitLocalCommand, isInspectDbUrl, isMcpCommand, isMcpOauth, isPluginsCommand, isProfileCommand, isSkillsCommand, isUnfollowedGitHookSync, readContextFile } from "../context.js";
 import { _ as upsertProfile, d as newProfileLocation, g as selectProfileName, h as resolveProfile, i as assertValidProfileName, l as locationForName, m as readProfiles, n as KEYRING_CREDENTIALS, p as profilesUsingPath, r as assertProfilesUsable, s as isKeyringPointer, t as DEFAULT_PROFILE, u as locationOf } from "../_chunks/profiles-DIB1av2Q.js";
 import { extendTokenSet } from "../utils/auth.js";
 import { AuthRefreshError, auth, classifyRefreshFailure, refreshToken } from "../auth.js";
@@ -293,6 +293,7 @@ const ensureAuth = async (props) => {
 	if (isCurrentBranchProbe(props)) return;
 	if (isConfigInit(props)) return;
 	if (isConfigAdd(props)) return;
+	if (isFunctionsTemplateCommand(props)) return;
 	if (isProfileCommand(props)) return;
 	if (isGitLocalCommand(props)) return;
 	if (isUnfollowedGitHookSync(props)) return;

package/dist/commands/config.js

@@ -1,12 +1,12 @@
 import { t as __exportAll } from "../_chunks/rolldown-runtime-8H4AJuhK.js";
-import { isCi } from "../env.js";
+import { isCi, isInteractiveTerminal } from "../env.js";
 import { log } from "../log.js";
 import { getApiClient } from "../api.js";
 import { contextBranch, ensureDirectoryGitignored, readContextFile } from "../context.js";
 import { getCliName } from "../utils/cli_name.js";
 import { NEON_SERVICES, NEON_SERVICE_LABELS, deprecatedServiceMessage, servicesFlagValue, servicesOption } from "../neon_services.js";
 import { FUNCTION_FILENAME, FUNCTION_SLUG, FUNCTION_TEMPLATE, REQUIRED_PACKAGES, parseConfigInitServices, renderFunctionSource, renderNeonConfig, renderNeonConfigFromView } from "../config_template.js";
-import { editNeonConfig } from "../config_edit.js";
+import { TYPESCRIPT_EXTENSION, asRelativeModulePath, editNeonConfig } from "../config_edit.js";
 import { toNeonConfigView } from "../config_format.js";
 import { declaredNeonServices } from "../config_services.js";
 import { loadProjectConfig, neonConfigFilename, projectConfigPath, projectDir } from "../project.js";
@@ -18,6 +18,7 @@ import { assertAiGatewayProvisionable, warnAiGateway } from "../utils/ai_gateway
 import { announceTargetBranch } from "../utils/branch_notice.js";
 import { renderAppliedChanges, renderBranchSettingConflicts, renderCustomDomainFollowup } from "../utils/config_diff.js";
 import { bundleEntry } from "../utils/esbuild.js";
+import { FUNCTION_SLUG_PATTERN, deriveFunctionSlug } from "../utils/function_slug.js";
 import { readGitContext } from "../utils/git.js";
 import { resolveHookEnv, runDeployAfterHook, runDeployBeforeHook } from "../utils/hooks.js";
 import { pickServicesInteractively } from "../utils/service_picker.js";
@@ -39,10 +40,13 @@ var config_exports = /* @__PURE__ */ __exportAll({
 	command: () => command,
 	createBranchFromPolicyOnCheckout: () => createBranchFromPolicyOnCheckout,
 	describe: () => describe,
+	ensureConfigPackages: () => ensureConfigPackages,
 	envFlag: () => envFlag,
 	envPullFlag: () => envPullFlag,
 	handler: () => handler,
 	initCmd: () => initCmd,
+	installCommandFrom: () => installCommandFrom,
+	missingDependencies: () => missingDependencies,
 	planCmd: () => planCmd,
 	status: () => status
 });
@@ -205,8 +209,8 @@ const seedFromBranch = async (props) => {
 	};
 };
 /** The install command to print, prefixed with a `cd` when the project is not the cwd. */
-const installCommandFrom = (dir, pm, missing) => {
-	const command = formatInstallCommand(pm, [...missing]);
+const installCommandFrom = (dir, pm, missing, options) => {
+	const command = formatInstallCommand(pm, [...missing], options);
 	const rel = relative(process.cwd(), dir);
 	if (rel === "") return command;
 	const target = rel.length <= dir.length ? rel : dir;
@@ -274,11 +278,7 @@ const initCmd = async (props) => {
 	await ensureConfigPackages(cwd, props);
 	if (!props.silent) log.info("Next: edit neon.ts, then run `neon config plan` to preview and `neon config apply`.");
 };
-/** The rule the platform enforces on function slugs, so a bad one fails before any write. */
-const FUNCTION_SLUG_PATTERN = /^[a-z0-9]{1,20}$/;
 const SCRIPT_EXTENSION = /\.(?:ts|mts|cts|js|mjs|cjs)$/;
-const TYPESCRIPT_EXTENSION = /\.(?:ts|mts|cts)$/;
-const asRelativeModulePath = (path) => path.startsWith("./") || path.startsWith("../") || path.startsWith("/") ? path : `./${path}`;
 const shellQuote = (value) => /^[\w@%+=:,./-]+$/.test(value) ? value : `'${value.replace(/'/g, "'\\''")}'`;
 /**
 * `explicitConfig` is the `--config` the user passed. The commands suggested afterwards must
@@ -322,7 +322,7 @@ const planAdd = (target, configPath, explicitConfig) => {
 			};
 		case "function": {
 			if (!FUNCTION_SLUG_PATTERN.test(target.slug)) {
-				const suggestion = target.slug.toLowerCase().replace(/[^a-z0-9]/g, "").slice(0, 20);
+				const suggestion = deriveFunctionSlug(target.slug);
 				throw new Error(`"${target.slug}" is not a valid function slug: use 1-20 lowercase letters and digits, no hyphens.` + (suggestion ? ` Try "${suggestion}".` : ""));
 			}
 			if (target.source !== void 0 && !SCRIPT_EXTENSION.test(target.source)) throw new Error(`--source must be a .ts or .js file, got "${target.source}". Declare a directory source in neon.ts by hand.`);
@@ -900,7 +900,7 @@ const reportPushResult = (props, result, mode, services) => {
 	out.text(`\nUtilized services: ${services.join(", ")}\n`);
 };
 /** A prompt needs both ends of a terminal, and would corrupt `-o json|yaml` on stdout. */
-const canPromptForApply = (props) => !isCi() && Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY) && props.output !== "json" && props.output !== "yaml";
+const canPromptForApply = (props) => isInteractiveTerminal() && props.output !== "json" && props.output !== "yaml";
 const askToApply = async (context) => {
 	const branch = JSON.stringify(context.branchName);
 	const message = context.protectedBranch && context.overrideUpdates ? `Branch ${branch} is protected, and this overrides the settings shown above. Apply anyway?` : context.protectedBranch ? `Branch ${branch} is protected. Apply to it anyway?` : `Override the settings shown above on branch ${branch}?`;
@@ -1110,4 +1110,4 @@ const createBranchFromPolicyOnCheckout = async (props) => {
 	}
 };
 //#endregion
-export { ConfigInstallFailed, addCmd, applyCmd, applyFlags, applyPolicyOnCreate, builder, command, createBranchFromPolicyOnCheckout, describe, envFlag, envPullFlag, handler, initCmd, planCmd, status, config_exports as t };
+export { ConfigInstallFailed, addCmd, applyCmd, applyFlags, applyPolicyOnCreate, builder, command, createBranchFromPolicyOnCheckout, describe, ensureConfigPackages, envFlag, envPullFlag, handler, initCmd, installCommandFrom, missingDependencies, planCmd, status, config_exports as t };

package/dist/commands/dev.js

@@ -4,12 +4,12 @@ import { isClaimableEnvTarget } from "../claimable/state.js";
 import { getCliName } from "../utils/cli_name.js";
 import { defaultDevEnvFiles, readEnvFile, resolveEnvFilePath } from "../env_file.js";
 import { l as functionBaseUrlKey } from "../_chunks/env-BpP3Dqpe.js";
-import { branchIdResolve } from "../utils/enrichers.js";
-import { bundleEntry } from "../utils/esbuild.js";
 import { a as resolveDevEnv } from "../_chunks/env-BNm69Qh8.js";
-import { envFlag } from "./config.js";
 import { findConfigFunctionBySource, resolveFunctionsFromConfig } from "../dev/functions.js";
 import { resolveWatchInputs } from "../dev/inputs.js";
+import { branchIdResolve } from "../utils/enrichers.js";
+import { bundleEntry } from "../utils/esbuild.js";
+import { envFlag } from "./config.js";
 import { existsSync, mkdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";

package/dist/commands/env.js

@@ -7,9 +7,9 @@ import { deprecatedServiceMessage, parseServices, servicesFlagValue, servicesOpt
 import { mergeEnvFile, readEnvFile, resolveEnvFilePath } from "../env_file.js";
 import { t as NEON_ENV_VAR_KEYS, u as isFunctionBaseUrlKey } from "../_chunks/env-BpP3Dqpe.js";
 import { ENV_PULL_KEY_HELP, ENV_PULL_SERVICES, envKeysForSelection, envPullFlagValue, ownedEnvServiceKeys, parseEnvPullKeys } from "../env_services.js";
+import { i as dropClaimableUnsupported, o as resolveNeonEnvVars } from "../_chunks/env-BNm69Qh8.js";
 import { fillSingleProject, resolveBranchRef } from "../utils/enrichers.js";
 import { warnAiGateway } from "../utils/ai_gateway_notice.js";
-import { i as dropClaimableUnsupported, o as resolveNeonEnvVars } from "../_chunks/env-BNm69Qh8.js";
 import { formatPulledEnv, pulledBranch } from "./env_output.js";
 import { existsSync } from "node:fs";
 import chalk from "chalk";

package/dist/commands/functions.js

@@ -7,8 +7,10 @@ import { createDeployment, deleteFunction, getFunction, listFunctions } from "..
 import { writer } from "../writer.js";
 import { branchIdFromProps, fillSingleProject } from "../utils/enrichers.js";
 import { bundleEntry } from "../utils/esbuild.js";
+import { FUNCTION_SLUG_HELP, FUNCTION_SLUG_PATTERN } from "../utils/function_slug.js";
 import { zipBundle } from "../utils/zip.js";
 import { DEPLOY_COMMANDS_EPILOGUE } from "./deploy_help.js";
+import { handleNew, listTemplates } from "./functions_new.js";
 import { statSync } from "node:fs";
 import { dirname } from "node:path";
 import { FUNCTION_SOURCE_ENTRIES } from "@neon/config";
@@ -77,8 +79,6 @@ const writeDeploymentErrorSection = (out, dep) => {
 		title: "Deployment error"
 	});
 };
-const SLUG_PATTERN = /^[a-z0-9]{1,20}$/;
-const SLUG_HELP = "Use 1-20 lowercase letters and digits (no hyphens or other characters).";
 const POLL_INTERVAL_OVERRIDE_MS = Number(process.env.NEON_FUNCTIONS_POLL_INTERVAL_MS) || void 0;
 const FIRST_POLL_DELAY_MS = 200;
 const POLL_INTERVAL_MS = 2e3;
@@ -101,7 +101,54 @@ const builder = (argv) => argv.usage("$0 function <sub-command> [options]").opti
 		describe: "Branch ID or name",
 		type: "string"
 	}
-}).middleware(fillSingleProject).command("deploy <slug>", "Deploy a function from a local directory", (yargs) => yargs.positional("slug", {
+}).middleware(fillSingleProject).command("new [template]", "Create a function from a Function Registry template", (yargs) => yargs.strict().positional("template", {
+	describe: "Template ID. Omit it in a terminal to pick one; `neon functions templates list` shows them all.",
+	type: "string"
+}).options({
+	"project-id": { hidden: true },
+	branch: { hidden: true },
+	slug: {
+		describe: "Function slug, also used as the directory name. A separate template keeps its own slugs and uses this only for the directory. Defaults to the template ID",
+		type: "string"
+	},
+	operation: {
+		describe: "Operation to include (repeatable). Without it, a TTY asks and anything else uses the recommended operations.",
+		type: "string",
+		array: true
+	},
+	"all-operations": {
+		describe: "Include every operation. Conflicts with --operation.",
+		type: "boolean"
+	},
+	yes: {
+		alias: ["y", "default"],
+		describe: "Skip prompts: use the recommended operations and install dependencies",
+		type: "boolean"
+	},
+	dir: {
+		describe: "Destination directory (defaults to functions/<slug> next to neon.ts)",
+		type: "string"
+	},
+	force: {
+		describe: "Overwrite differing files and keep an existing neon.ts declaration",
+		type: "boolean"
+	},
+	install: {
+		describe: "Install the template's dependencies, plus @neon/config and @neon/env when neon.ts is created. A TTY asks when omitted, --yes installs, and anything else leaves the install command in Next.",
+		type: "boolean"
+	},
+	"add-to-config": {
+		describe: "Declare the function in neon.ts, creating it when missing. On by default; use --no-add-to-config to skip.",
+		type: "boolean"
+	},
+	config: {
+		describe: "Path to the neon.ts to edit (defaults to the neon.ts next to .neon, or in cwd without one; created there when missing)",
+		type: "string"
+	}
+}), (args) => handleNew(args)).command("templates", "Browse Function Registry templates", (yargs) => yargs.command("list", "List function templates", (yargs) => yargs.strict().options({
+	"project-id": { hidden: true },
+	branch: { hidden: true }
+}), (args) => listTemplates(args))).command("deploy <slug>", "Deploy a function from a local directory", (yargs) => yargs.positional("slug", {
 	describe: "Function slug (1-20 lowercase letters and digits)",
 	type: "string",
 	demandOption: true
@@ -200,7 +247,7 @@ const isTransient = (err) => isNeonApiError(err) && (err.status === void 0 || er
 const deploy = async (props) => {
 	if (props.path !== void 0 || props.entry !== void 0) throw new Error(`--path and --entry were removed. Use --src <dir>; the entry point is discovered as ${FUNCTION_SOURCE_ENTRIES.join(", ")} in that directory.`);
 	if (!(props.src !== void 0 || props.env !== void 0 || props.runtime !== void 0 || props.bundle === false)) throw new Error(`Provide at least one option to deploy, e.g. --src, --env, or --no-bundle. See: ${getCliName()} function deploy --help.`);
-	if (!SLUG_PATTERN.test(props.slug)) throw new Error(`Invalid function slug "${props.slug}". ${SLUG_HELP}`);
+	if (!FUNCTION_SLUG_PATTERN.test(props.slug)) throw new Error(`Invalid function slug "${props.slug}". ${FUNCTION_SLUG_HELP}`);
 	const src = props.src ?? ".";
 	const runtime = props.runtime ?? "nodejs24";
 	const environment = parseEnv(props.env);
@@ -392,7 +439,7 @@ const listDomains = async (props) => {
 	});
 };
 const registerDomain = async (props) => {
-	if (!SLUG_PATTERN.test(props.slug)) throw new Error(`Invalid function slug "${props.slug}". ${SLUG_HELP}`);
+	if (!FUNCTION_SLUG_PATTERN.test(props.slug)) throw new Error(`Invalid function slug "${props.slug}". ${FUNCTION_SLUG_HELP}`);
 	const branchId = await branchIdFromProps(props);
 	const registered = await retryOnLock(() => registerCustomDomain(props.apiClient, props.projectId, branchId, {
 		domain: props.domain,

package/dist/commands/functions_new.js

@@ -0,0 +1,332 @@
+import { isInteractiveTerminal } from "../env.js";
+import { log } from "../log.js";
+import { getCliName } from "../utils/cli_name.js";
+import { projectConfigPath, projectDir } from "../project.js";
+import { resolveEnvFilePath } from "../env_file.js";
+import { installArgs, resolvePackageManager, runCommand } from "../utils/package_manager.js";
+import { writer } from "../writer.js";
+import { formatInitDone, printInitDone } from "../init/chrome.js";
+import { FUNCTION_SLUG_PATTERN, deriveFunctionSlug } from "../utils/function_slug.js";
+import { displayPath } from "./env_output.js";
+import { ensureConfigPackages, installCommandFrom, missingDependencies } from "./config.js";
+import { recommendedOperations } from "../functions/registry.js";
+import { collidingFiles, operationsFromFlags, planConfigRegistration, planEnvExample, planScaffold, writeScaffold } from "../functions/scaffold.js";
+import { describeRegistrySource, openRegistry } from "../functions/source.js";
+import { writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import prompts from "prompts";
+//#region src/commands/functions_new.ts
+const TEMPLATE_FIELDS = [
+	"id",
+	"title",
+	"provider",
+	"description"
+];
+const NEW_FUNCTION_FIELDS = [
+	"template",
+	"layout",
+	"operations",
+	"routes",
+	"functions",
+	"directory",
+	"config",
+	"dependencies",
+	"installed",
+	"environment",
+	"env_example",
+	"next_steps"
+];
+const structured = (props) => props.output === "json" || props.output === "yaml";
+const providerOf = (item) => item.provider ?? "Neon";
+const writeTemplates = (props, entries) => writer(props).end(entries.map((entry) => ({
+	id: entry.id,
+	title: entry.title,
+	provider: providerOf(entry),
+	description: entry.description
+})), {
+	fields: TEMPLATE_FIELDS,
+	emptyMessage: "No function templates found."
+});
+const listTemplates = async (props) => {
+	writeTemplates(props, (await openRegistry()).entries);
+};
+const unknownTemplate = (id, registry) => /* @__PURE__ */ new Error(`Unknown function template "${id}" in ${describeRegistrySource(registry.source)}. Available templates: ${registry.entries.map((entry) => entry.id).join(", ")}.`);
+const pickOperations = async (operations, provider) => {
+	const answer = await prompts({
+		type: "multiselect",
+		name: "value",
+		message: `Which ${provider} operations should this function expose?`,
+		hint: "Space to toggle. Enter to confirm.",
+		choices: operations.map((operation) => ({
+			title: operation.id,
+			description: operation.description,
+			value: operation.id,
+			selected: operation.recommended
+		})),
+		min: 1,
+		instructions: false
+	});
+	if (!Array.isArray(answer.value)) return void 0;
+	const chosen = new Set(answer.value);
+	return operations.filter((operation) => chosen.has(operation.id));
+};
+const confirm = async (message, initial) => {
+	return (await prompts({
+		type: "confirm",
+		name: "value",
+		message,
+		initial
+	})).value;
+};
+const assertSlug = (slug) => {
+	if (slug === void 0 || FUNCTION_SLUG_PATTERN.test(slug)) return;
+	const suggestion = deriveFunctionSlug(slug);
+	throw new Error(`"${slug}" is not a valid function slug: use 1-20 lowercase letters and digits, no hyphens.` + (suggestion ? ` Try "${suggestion}".` : ""));
+};
+const scaffoldFromTemplate = async (options) => {
+	assertSlug(options.slug);
+	const registry = options.registry ?? await openRegistry();
+	const entry = registry.entries.find(({ id }) => id === options.template);
+	if (!entry) throw unknownTemplate(options.template, registry);
+	const cwd = options.cwd ?? process.cwd();
+	const { interactive } = options;
+	const loaded = await registry.load(entry);
+	const { template } = loaded;
+	const provider = providerOf(template);
+	let operations = operationsFromFlags(template, {
+		operations: options.operations,
+		allOperations: options.allOperations
+	}) ?? recommendedOperations(template.operations ?? []);
+	if (interactive && options.operations === void 0 && options.allOperations === void 0 && (template.operations?.length ?? 0) > 1) {
+		const picked = await pickOperations(template.operations ?? [], provider);
+		if (picked === void 0) return { cancelled: true };
+		operations = picked;
+	}
+	const slug = options.slug ?? deriveFunctionSlug(template.id);
+	const plan = planScaffold(loaded, operations, slug);
+	const location = {
+		cwd,
+		...options.contextFile ? { contextFile: options.contextFile } : {}
+	};
+	const configPath = options.config ? resolve(cwd, options.config) : projectConfigPath(location) ?? join(projectDir(location), "neon.ts");
+	const projectRoot = dirname(configPath);
+	const targetDir = options.dir ? resolve(cwd, options.dir) : join(projectRoot, "functions", slug);
+	const directory = displayPath(targetDir, cwd);
+	const collisions = collidingFiles(targetDir, plan.files);
+	if (collisions.length > 0 && options.force !== true) {
+		const list = collisions.join(", ");
+		if (!interactive || options.force === false) throw new Error(`${directory} already has different ${list}. Pass --force to overwrite, or --dir to scaffold elsewhere.`);
+		if (await confirm(`${directory} already has different ${list}. Overwrite?`, false) !== true) return { cancelled: true };
+	}
+	const register = options.addToConfig !== false;
+	const registration = register ? planConfigRegistration(configPath, targetDir, plan.functions) : void 0;
+	if (registration && registration.alreadyDeclared.length > 0 && !options.force) {
+		const declared = `${displayPath(configPath, cwd)} already declares ${registration.alreadyDeclared.join(", ")}.`;
+		throw new Error(plan.layout === "separate" ? `${declared} The template sets these slugs, so --slug cannot change them. Remove them from neon.ts, pass --force to keep the declarations and overwrite the files, or pass --no-add-to-config.` : `${declared} Pass --slug to pick another one, --force to keep the declaration and overwrite the files, or --no-add-to-config.`);
+	}
+	const envExample = planEnvExample(projectRoot, template.environment);
+	writeScaffold(targetDir, plan.files);
+	if (registration?.source !== void 0) writeFileSync(configPath, registration.source);
+	if (envExample.contents !== void 0) writeFileSync(envExample.path, envExample.contents);
+	const { dependencies } = template;
+	const pm = resolvePackageManager(projectRoot);
+	const installHint = (packages, exact = false) => installCommandFrom(projectRoot, pm, packages, { exact });
+	const configPackages = registration?.created ? missingDependencies(projectRoot) : [];
+	const packages = [...configPackages, ...dependencies];
+	let install = options.install === true;
+	if (options.install === void 0 && packages.length > 0 && interactive) install = await confirm(`Install ${packages.join(", ")} with ${pm}?`, true) === true;
+	if (configPackages.length > 0) await ensureConfigPackages(projectRoot, {
+		install,
+		packageManager: pm,
+		...options.run ? { run: options.run } : {},
+		silent: true
+	});
+	let installed = false;
+	if (install && dependencies.length > 0) {
+		installed = await (options.run ?? runCommand)(pm, installArgs(pm, dependencies, { exact: true }), projectRoot);
+		if (!installed) log.warning("Could not install %s. Run by hand: `%s`", dependencies.join(", "), installHint(dependencies, true));
+	}
+	const cli = getCliName();
+	const functions = plan.functions.map((fn) => ({
+		slug: fn.slug,
+		name: fn.name,
+		...fn.operation ? { operation: fn.operation } : {},
+		source: displayPath(join(targetDir, fn.file), cwd)
+	}));
+	const nextSteps = [];
+	const next = [];
+	const missingConfig = registration?.created ? missingDependencies(projectRoot) : [];
+	if (missingConfig.length > 0) {
+		nextSteps.push(`Install the Neon config packages: \`${installHint(missingConfig)}\``);
+		next.push(installHint(missingConfig));
+	}
+	if (dependencies.length > 0 && !installed) {
+		nextSteps.push(`Install the template's dependencies: \`${installHint(dependencies, true)}\``);
+		next.push(installHint(dependencies, true));
+	}
+	const environment = template.environment.map(({ name }) => name);
+	const variables = template.environment.map((variable) => `${variable.name} (${variable.description})`).join(", ");
+	const envFile = displayPath(resolveEnvFilePath(location), cwd);
+	const names = environment.join(", ");
+	if (variables && register) {
+		const them = environment.length === 1 ? "it" : "them";
+		nextSteps.push(`Set ${variables} in ${envFile}. \`${cli} dev\` reads ${them} from your shell, so export ${them} there too.`);
+		next.push(`Set ${names} in ${envFile}, and export ${them} for ${cli} dev`);
+	} else if (variables) {
+		nextSteps.push(`Set ${variables} in your shell.`);
+		next.push(`Set ${names} in your shell`);
+	}
+	if (plan.routes) nextSteps.push(`Routes: ${plan.routes.join(", ")}. Other paths return 404.`);
+	if (register) {
+		const flag = options.config ? ` --config ${options.config}` : "";
+		const envFlag = variables ? ` --env ${envFile}` : "";
+		nextSteps.push(`Next: \`${cli} dev${flag}\` to run it locally, \`${cli} config apply${flag}${envFlag}\` to deploy.`);
+		next.push(`${cli} dev${flag}`, `${cli} config apply${flag}${envFlag}`);
+	} else {
+		const envFlags = environment.map((name) => ` --env ${name}=<value>`).join("");
+		for (const fn of functions) {
+			nextSteps.push(`Next: \`${cli} dev --source ${fn.source}\` to run ${fn.slug} locally, \`${cli} functions deploy ${fn.slug} --src ${fn.source}${envFlags}\` to deploy.`);
+			next.push(`${cli} dev --source ${fn.source}`, `${cli} functions deploy ${fn.slug} --src ${fn.source}${envFlags}`);
+		}
+	}
+	return {
+		cancelled: false,
+		template: template.id,
+		title: template.title,
+		provider,
+		layout: plan.layout,
+		operations: operations.map(({ id }) => id),
+		...plan.routes ? { routes: plan.routes } : {},
+		functions,
+		directory,
+		...registration && registration.changes.length > 0 ? { config: {
+			path: displayPath(configPath, cwd),
+			action: registration.created ? "created" : "updated",
+			changes: registration.changes
+		} } : {},
+		dependencies: [...dependencies],
+		packages,
+		packageManager: pm,
+		installed,
+		install: packages.length === 0 || !install ? "skipped" : missingConfig.length > 0 || dependencies.length > 0 && !installed ? "failed" : "installed",
+		environment,
+		...envExample.added.length > 0 ? { envExample: {
+			path: displayPath(envExample.path, cwd),
+			added: envExample.added
+		} } : {},
+		nextSteps,
+		next
+	};
+};
+const formatNewFunctionDone = (result) => {
+	const plural = result.functions.length !== 1;
+	const rows = [
+		{
+			label: "Template",
+			value: `${result.title} (${result.provider})`
+		},
+		{
+			label: plural ? "Functions" : "Function",
+			value: result.functions.map(({ slug }) => slug).join(", ")
+		},
+		{
+			label: "Directory",
+			value: result.directory
+		}
+	];
+	if (result.routes) rows.push({
+		label: "Routes",
+		value: `${result.routes.join(", ")} (other paths return 404)`
+	});
+	rows.push({
+		label: "Config",
+		value: result.config ? `${result.config.path} ${result.config.action}: ${result.config.changes.join(", ")}` : "not added"
+	});
+	if (result.packages.length > 0) rows.push({
+		label: "Dependencies",
+		value: result.install === "failed" ? "install failed" : result.install === "installed" ? `installed with ${result.packageManager}` : "not installed"
+	});
+	if (result.envExample) rows.push({
+		label: "Env",
+		value: `${result.envExample.added.join(", ")} added to ${result.envExample.path}`
+	});
+	else if (result.environment.length > 0) rows.push({
+		label: "Env",
+		value: result.environment.join(", ")
+	});
+	return formatInitDone({
+		heading: result.install === "failed" ? "Setup did not finish." : plural ? "Functions created." : "Function created.",
+		rows,
+		next: result.next
+	});
+};
+const pickTemplate = async (entries) => {
+	const answer = await prompts({
+		type: "select",
+		name: "value",
+		message: "Which template would you like to use?",
+		choices: entries.map((entry) => ({
+			title: `${entry.title} (${providerOf(entry)})`,
+			description: entry.description,
+			value: entry.id
+		})),
+		initial: 0
+	});
+	return typeof answer.value === "string" ? answer.value : void 0;
+};
+const handleNew = async (props) => {
+	const interactive = props.yes !== true && !structured(props) && isInteractiveTerminal();
+	assertSlug(props.slug);
+	const registry = await openRegistry();
+	let template = props.template;
+	if (template === void 0) {
+		if (!interactive) throw new Error(`No template selected. Re-run in an interactive terminal to pick one, or pass a template ID. Available templates: ${registry.entries.map((entry) => entry.id).join(", ")}.`);
+		template = await pickTemplate(registry.entries);
+		if (template === void 0) {
+			log.info("Cancelled; no files were changed.");
+			return;
+		}
+	}
+	if (!structured(props)) log.info("Fetching template \"%s\" from the Function Registry…", template);
+	const result = await scaffoldFromTemplate({
+		template,
+		slug: props.slug,
+		operations: props.operation,
+		allOperations: props.allOperations,
+		dir: props.dir,
+		force: props.force,
+		install: props.install ?? (props.yes === true ? true : void 0),
+		addToConfig: props.addToConfig,
+		config: props.config,
+		contextFile: props.contextFile,
+		registry,
+		interactive
+	});
+	if (result.cancelled) {
+		log.info("Cancelled; no files were changed.");
+		return;
+	}
+	if (structured(props)) {
+		writer(props).end({
+			template: result.template,
+			layout: result.layout,
+			operations: result.operations,
+			routes: result.routes ?? null,
+			functions: result.functions,
+			directory: result.directory,
+			config: result.config ? {
+				path: result.config.path,
+				action: result.config.action
+			} : null,
+			dependencies: result.dependencies,
+			installed: result.installed,
+			environment: result.environment,
+			env_example: result.envExample ?? null,
+			next_steps: result.nextSteps
+		}, { fields: NEW_FUNCTION_FIELDS });
+		return;
+	}
+	printInitDone(formatNewFunctionDone(result));
+};
+//#endregion
+export { formatNewFunctionDone, handleNew, listTemplates, scaffoldFromTemplate };

package/dist/commands/link.js

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "../_chunks/rolldown-runtime-8H4AJuhK.js";
-import { isCi } from "../env.js";
+import { isInteractiveTerminal } from "../env.js";
 import { log } from "../log.js";
 import { isNeonApiError, messageFromBody } from "../api.js";
 import { r as defaultDir } from "../_chunks/paths-DMq0Lt7a.js";
@@ -30,7 +30,7 @@ var link_exports = /* @__PURE__ */ __exportAll({
 });
 const PROJECTS_LIST_LIMIT = 100;
 const CREATE_NEW_SENTINEL = "__create_new__";
-const canPromptInteractively = () => !isCi() && Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
+const canPromptInteractively = () => isInteractiveTerminal();
 const nonInteractiveLinkCommands = () => {
 	const cli = getCliName();
 	return [

package/dist/commands/subscribe.js

@@ -1,6 +1,6 @@
 import { writer } from "../writer.js";
-import { branchIdFromProps } from "../utils/enrichers.js";
 import { o as resolveNeonEnvVars } from "../_chunks/env-BNm69Qh8.js";
+import { branchIdFromProps } from "../utils/enrichers.js";
 import YAML from "yaml";
 //#region src/commands/subscribe.ts
 const builder = (argv) => argv.usage("$0 realtime subscribe \"<query>\" [options]").positional("query", {

package/dist/config_edit.js

@@ -9,6 +9,8 @@ import { renderKey } from "./config_template.js";
 * file already declares it (`changes` is empty). A file whose layout the scanner cannot
 * place an edit into is refused with the exact lines to add by hand.
 */
+const TYPESCRIPT_EXTENSION = /\.(?:ts|mts|cts)$/;
+const asRelativeModulePath = (path) => path.startsWith("./") || path.startsWith("../") || path.startsWith("/") ? path : `./${path}`;
 var ConfigEditError = class extends Error {
 	constructor(message) {
 		super(message);
@@ -262,9 +264,12 @@ const apply = (source, edit) => {
 				run((parsed) => setToggle(parsed, "dataApi"));
 			}
 			break;
-		case "function":
-			run((parsed) => addNamed(parsed, "functions", edit.slug, [`${renderKey(edit.slug)}: { name: ${JSON.stringify(edit.name)}, source: ${JSON.stringify(edit.source)} },`]));
+		case "function": {
+			const assertion = edit.typescript === false ? "" : "!";
+			const env = edit.env?.length ? `, env: { ${edit.env.map((name) => `${renderKey(name)}: process.env.${name}${assertion}`).join(", ")} }` : "";
+			run((parsed) => addNamed(parsed, "functions", edit.slug, [`${renderKey(edit.slug)}: { name: ${JSON.stringify(edit.name)}, source: ${JSON.stringify(edit.source)}${env} },`]));
 			break;
+		}
 		case "bucket": run((parsed) => addNamed(parsed, "buckets", edit.name, [`${renderKey(edit.name)}: { access: ${JSON.stringify(edit.access)} },`]));
 	}
 	return {
@@ -283,4 +288,4 @@ const editNeonConfig = (source, edit) => {
 	return result;
 };
 //#endregion
-export { ConfigEditError, editNeonConfig };
+export { ConfigEditError, TYPESCRIPT_EXTENSION, asRelativeModulePath, editNeonConfig };

package/dist/context.js

@@ -41,6 +41,7 @@ const isConfigInit = (args) => args._[0] === "config" && args._[1] === "init" &&
 * middleware and the single-project resolver skip it, like {@link isConfigInit}.
 */
 const isConfigAdd = (args) => args._[0] === "config" && args._[1] === "add";
+const isFunctionsTemplateCommand = (args) => (args._[0] === "functions" || args._[0] === "function") && (args._[1] === "new" || args._[1] === "templates");
 /**
 * `neon profile …` manages credentials on disk and never calls the Neon API, so the global
 * auth middleware must skip it — mirroring {@link isConfigInit}.
@@ -359,4 +360,4 @@ const globToRegExp = (pattern) => {
 	return new RegExp(`^${source}$`);
 };
 //#endregion
-export { CONTEXT_FILE, applyContext, contextBranch, currentContextFile, enrichFromContext, ensureDirectoryGitignored, ensureGitignored, gitBranchMap, gitBranchMapping, isApiKeysCommand, isAskCommand, isClaimCommand, isConfigAdd, isConfigInit, isCurrentBranchProbe, isDocsCommand, isFeedbackCommand, isGitLocalCommand, isInspectDbUrl, isMcpCommand, isMcpOauth, isPluginsCommand, isProfileCommand, isSkillsCommand, isUnfollowedGitHookSync, readContextFile, setContext, setGitBranchMap, setGitBranchMapping, setGitFollow, updateContextFile, walkContextFile };
+export { CONTEXT_FILE, applyContext, contextBranch, currentContextFile, enrichFromContext, ensureDirectoryGitignored, ensureGitignored, gitBranchMap, gitBranchMapping, isApiKeysCommand, isAskCommand, isClaimCommand, isConfigAdd, isConfigInit, isCurrentBranchProbe, isDocsCommand, isFeedbackCommand, isFunctionsTemplateCommand, isGitLocalCommand, isInspectDbUrl, isMcpCommand, isMcpOauth, isPluginsCommand, isProfileCommand, isSkillsCommand, isUnfollowedGitHookSync, readContextFile, setContext, setGitBranchMap, setGitBranchMapping, setGitFollow, updateContextFile, walkContextFile };

package/dist/env.js

@@ -2,6 +2,7 @@
 const isCi = () => {
 	return process.env.CI !== "false" && Boolean(process.env.CI);
 };
+const isInteractiveTerminal = () => !isCi() && Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
 const isDebug = () => {
 	return Boolean(process.env.DEBUG);
 };
@@ -38,4 +39,4 @@ const getGithubEnvVars = (env) => {
 	return Object.fromEntries(map);
 };
 //#endregion
-export { getCliAgent, getGithubEnvVars, isCi, isDebug };
+export { getCliAgent, getGithubEnvVars, isCi, isDebug, isInteractiveTerminal };

package/dist/functions/registry.js

@@ -0,0 +1,174 @@
+import { FUNCTION_SLUG_PATTERN } from "../utils/function_slug.js";
+//#region src/functions/registry.ts
+const MAX_PATH_LENGTH = 255;
+const MAX_INDEX_ENTRIES = 500;
+const MAX_OPERATIONS = 40;
+const MAX_LOGO_URL_LENGTH = 2048;
+const MAX_FILE_BYTES = 262144;
+const MAX_TOTAL_BYTES = 2097152;
+const MAX_JSON_BYTES = 1048576;
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isText = (value) => typeof value === "string" && value.trim() !== "";
+const matches = (value, pattern) => typeof value === "string" && pattern.test(value);
+const isOptionalString = (value) => value === void 0 || typeof value === "string";
+const TEMPLATE_ID = /^[a-z0-9][a-z0-9-]*$/;
+const OPERATION_ID = /^[a-z0-9][a-z0-9-]*$/;
+const OPERATION_SLUG = FUNCTION_SLUG_PATTERN;
+const ENV_NAME = /^[A-Z_][A-Z0-9_]*$/;
+const SINGLE_LINE = /^[^\r\n]*$/;
+const WINDOWS_ABSOLUTE = /^[A-Za-z]:/;
+const SOURCE_EXTENSION = /\.ts$/;
+const ROUTE_PATTERN = /^\/[A-Za-z0-9\-._~/]*$/;
+const EXACT_DEPENDENCY = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*@\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const TEMPLATE_LAYOUTS = ["router", "separate"];
+const REGISTRY_CONTRACT = {
+	layouts: TEMPLATE_LAYOUTS,
+	requiredTemplateFields: [
+		"id",
+		"title",
+		"description",
+		"layout"
+	],
+	requiredOperationFields: [
+		"id",
+		"title",
+		"description",
+		"source",
+		"recommended"
+	],
+	templateId: TEMPLATE_ID,
+	operationId: OPERATION_ID,
+	operationSlug: OPERATION_SLUG,
+	envName: ENV_NAME,
+	envDescription: SINGLE_LINE,
+	source: SOURCE_EXTENSION,
+	route: ROUTE_PATTERN,
+	dependency: EXACT_DEPENDENCY,
+	maxOperations: MAX_OPERATIONS,
+	maxIndexEntries: MAX_INDEX_ENTRIES,
+	maxFileBytes: MAX_FILE_BYTES,
+	maxJsonBytes: MAX_JSON_BYTES
+};
+const isContainedRelativePath = (value) => value !== "" && value.length <= MAX_PATH_LENGTH && !value.includes("\0") && !value.includes("\\") && !value.startsWith("/") && !WINDOWS_ABSOLUTE.test(value) && !value.split("/").some((part) => part === "" || part === "." || part === "..");
+const isSafeSourcePath = (value) => isContainedRelativePath(value) && SOURCE_EXTENSION.test(value);
+const isDisplayLogoUrl = (value) => {
+	if (value.length > MAX_LOGO_URL_LENGTH || !URL.canParse(value)) return false;
+	return new URL(value).protocol === "https:";
+};
+const stringList = (value) => {
+	if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) return;
+	return value;
+};
+const parseEnvironment = (value) => {
+	if (!Array.isArray(value)) return void 0;
+	const result = [];
+	for (const item of value) {
+		if (!isRecord(item) || typeof item.name !== "string" || typeof item.description !== "string" || !ENV_NAME.test(item.name) || !SINGLE_LINE.test(item.description)) return;
+		result.push({
+			name: item.name,
+			description: item.description
+		});
+	}
+	return result;
+};
+const parseTemplateOperations = (value, layout) => {
+	if (!Array.isArray(value) || value.length === 0) return void 0;
+	if (value.length > MAX_OPERATIONS) return void 0;
+	const operations = [];
+	const ids = /* @__PURE__ */ new Set();
+	const routes = /* @__PURE__ */ new Set();
+	const slugs = /* @__PURE__ */ new Set();
+	const sources = /* @__PURE__ */ new Set();
+	let recommended = 0;
+	for (const item of value) {
+		if (!isRecord(item) || !matches(item.id, OPERATION_ID) || ids.has(item.id) || !isText(item.title) || !isText(item.description) || typeof item.source !== "string" || !isSafeSourcePath(item.source) || sources.has(item.source) || !isOptionalString(item.route) || typeof item.recommended !== "boolean") return;
+		const operation = {
+			id: item.id,
+			title: item.title,
+			description: item.description,
+			source: item.source,
+			recommended: item.recommended
+		};
+		if (layout === "separate") {
+			if (typeof item.slug !== "string" || !OPERATION_SLUG.test(item.slug) || slugs.has(item.slug)) return;
+			slugs.add(item.slug);
+			operation.slug = item.slug;
+		} else {
+			const route = item.route === void 0 ? `/${item.id}` : item.route;
+			if (!ROUTE_PATTERN.test(route) || routes.has(route)) return;
+			routes.add(route);
+			operation.route = route;
+		}
+		if (item.recommended) recommended++;
+		ids.add(item.id);
+		sources.add(item.source);
+		operations.push(operation);
+	}
+	if (recommended < 1) return void 0;
+	return operations;
+};
+const recommendedOperations = (operations) => operations.filter((operation) => operation.recommended);
+const resolveOperationById = (operations, id) => {
+	const operation = operations.find((candidate) => candidate.id === id);
+	if (!operation) throw new Error(`Unknown operation "${id}". Available operations: ${operations.map((candidate) => candidate.id).join(", ")}.`);
+	return operation;
+};
+const parseTemplateItem = (text, expectedId) => {
+	const data = JSON.parse(text);
+	if (!isRecord(data)) throw new Error("Invalid template.json: expected a JSON object.");
+	if (!matches(data.id, TEMPLATE_ID) || expectedId !== void 0 && data.id !== expectedId) throw new Error("Invalid template.json: bad or mismatched id.");
+	if (!isText(data.title) || !isText(data.description)) throw new Error(`Invalid template.json for "${data.id}": missing title or description.`);
+	if (!isOptionalString(data.provider)) throw new Error(`Invalid template.json for "${data.id}": provider must be a string.`);
+	if (typeof data.layout !== "string" || !TEMPLATE_LAYOUTS.includes(data.layout)) throw new Error(`Invalid template.json for "${data.id}": layout must be one of ${TEMPLATE_LAYOUTS.join(", ")}.`);
+	const layout = data.layout;
+	const dependencies = stringList(data.dependencies ?? []);
+	if (dependencies === void 0 || !dependencies.every((dependency) => EXACT_DEPENDENCY.test(dependency))) throw new Error(`Invalid template.json for "${data.id}": dependencies must be exact name@version pins.`);
+	const environment = parseEnvironment(data.environment ?? []);
+	if (environment === void 0) throw new Error(`Invalid template.json for "${data.id}": environment names must be UPPER_SNAKE with a one-line description.`);
+	let operations;
+	if (data.operations !== void 0) {
+		operations = parseTemplateOperations(data.operations, layout);
+		if (operations === void 0) throw new Error(`Invalid template.json for "${data.id}": malformed operations.`);
+	}
+	return {
+		id: data.id,
+		...data.provider ? { provider: data.provider } : {},
+		title: data.title,
+		description: data.description,
+		layout,
+		dependencies,
+		environment,
+		...operations ? { operations } : {}
+	};
+};
+const parseRegistryIndex = (text) => {
+	const data = JSON.parse(text);
+	const items = isRecord(data) ? data.templates : void 0;
+	if (!Array.isArray(items)) throw new Error("Invalid function registry: missing \"templates\" array.");
+	if (items.length > MAX_INDEX_ENTRIES) throw new Error(`Invalid function registry: ${items.length} templates, more than the ${MAX_INDEX_ENTRIES} the CLI reads.`);
+	const entries = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const [index, item] of items.entries()) {
+		const at = `templates[${index}]${isRecord(item) && typeof item.id === "string" ? ` ("${item.id}")` : ""}`;
+		const invalid = (reason) => /* @__PURE__ */ new Error(`Invalid function registry: ${at} ${reason}.`);
+		if (!isRecord(item)) throw invalid("is not an object");
+		if (!matches(item.id, TEMPLATE_ID)) throw invalid("has a bad id");
+		if (seen.has(item.id)) throw invalid("repeats an id");
+		if (!isText(item.title) || !isText(item.description)) throw invalid("is missing a title or description");
+		if (!isOptionalString(item.provider)) throw invalid("has a provider that is not a string");
+		if (typeof item.path !== "string" || !isContainedRelativePath(item.path)) throw invalid("has a missing or unsafe path");
+		if (item.logo !== void 0 && (typeof item.logo !== "string" || !isDisplayLogoUrl(item.logo))) throw invalid("has a logo that is not an https:// URL");
+		seen.add(item.id);
+		entries.push({
+			id: item.id,
+			...item.provider ? { provider: item.provider } : {},
+			title: item.title,
+			description: item.description,
+			path: item.path,
+			...item.logo ? { logo: item.logo } : {}
+		});
+	}
+	return entries;
+};
+//#endregion
+export { MAX_FILE_BYTES, MAX_JSON_BYTES, MAX_TOTAL_BYTES, REGISTRY_CONTRACT, TEMPLATE_LAYOUTS, isContainedRelativePath, parseEnvironment, parseRegistryIndex, parseTemplateItem, parseTemplateOperations, recommendedOperations, resolveOperationById };

package/dist/functions/scaffold.js

@@ -0,0 +1,149 @@
+import { renderNeonConfig } from "../config_template.js";
+import { TYPESCRIPT_EXTENSION, asRelativeModulePath, editNeonConfig } from "../config_edit.js";
+import { readEnvFile } from "../env_file.js";
+import { FUNCTION_SLUG_HELP, FUNCTION_SLUG_PATTERN, deriveFunctionSlug } from "../utils/function_slug.js";
+import { resolveOperationById } from "./registry.js";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+//#region src/functions/scaffold.ts
+const operationsFromFlags = (template, choice) => {
+	const operations = template.operations ?? [];
+	const explicit = choice.operations ?? [];
+	if (choice.allOperations && explicit.length > 0) throw new Error("Pass either --all-operations or --operation, not both.");
+	if (operations.length === 0 && (choice.allOperations || explicit.length > 0)) throw new Error(`Template "${template.id}" has no operations. Remove --operation and --all-operations.`);
+	if (choice.allOperations) return [...operations];
+	if (explicit.length > 0) return [...new Set(explicit)].map((id) => resolveOperationById(operations, id));
+};
+const routeOf = (operation) => operation.route ?? `/${operation.id}`;
+const routerSource = (operations) => {
+	return `${operations.map((operation, index) => `import op${index} from "./${operation.id}";`).join("\n")}
+
+const routes: Record<
+\tstring,
+\t{ fetch: (request: Request) => Response | Promise<Response> }
+> = {
+${operations.map((operation, index) => `\t${JSON.stringify(routeOf(operation))}: op${index},`).join("\n")}
+};
+
+export default {
+\tfetch(request: Request): Response | Promise<Response> {
+\t\tconst { pathname } = new URL(request.url);
+\t\tconst route = routes[pathname];
+\t\tif (!route) {
+\t\t\treturn Response.json(
+\t\t\t\t{ error: "Not found", routes: Object.keys(routes) },
+\t\t\t\t{ status: 404 },
+\t\t\t);
+\t\t}
+\t\treturn route.fetch(request);
+\t},
+};
+`;
+};
+const sourceOf = (loaded, path) => {
+	const text = loaded.sources.get(path);
+	if (text === void 0) throw new Error(`Template "${loaded.template.id}" did not load ${path}.`);
+	return text;
+};
+const planScaffold = (loaded, operations, slug) => {
+	const { template } = loaded;
+	const env = template.environment.map(({ name }) => name);
+	if (!FUNCTION_SLUG_PATTERN.test(slug)) throw new Error(`Invalid function slug "${slug}". ${FUNCTION_SLUG_HELP}`);
+	if ((template.operations?.length ?? 0) === 0) return {
+		layout: template.layout,
+		files: [{
+			path: "index.ts",
+			contents: sourceOf(loaded, "functions/index.ts")
+		}],
+		functions: [{
+			slug,
+			name: template.title,
+			file: "index.ts",
+			env
+		}]
+	};
+	if (operations.length === 0) throw new Error("Select at least one operation.");
+	const modules = operations.map((operation) => ({
+		path: `${operation.id}.ts`,
+		contents: sourceOf(loaded, operation.source)
+	}));
+	if (template.layout === "separate") return {
+		layout: "separate",
+		files: modules,
+		functions: operations.map((operation) => ({
+			slug: operation.slug ?? deriveFunctionSlug(operation.id),
+			name: operation.title,
+			operation: operation.id,
+			file: `${operation.id}.ts`,
+			env
+		}))
+	};
+	return {
+		layout: "router",
+		files: [...modules, {
+			path: "index.ts",
+			contents: routerSource(operations)
+		}],
+		functions: [{
+			slug,
+			name: template.title,
+			file: "index.ts",
+			env
+		}],
+		routes: operations.map(routeOf)
+	};
+};
+const collidingFiles = (targetDir, files) => files.filter(({ path, contents }) => {
+	const target = join(targetDir, path);
+	return existsSync(target) && readFileSync(target, "utf8") !== contents;
+}).map(({ path }) => path);
+const writeScaffold = (targetDir, files) => {
+	mkdirSync(targetDir, { recursive: true });
+	for (const { path, contents } of files) writeFileSync(join(targetDir, path), contents);
+};
+const planConfigRegistration = (configPath, targetDir, functions) => {
+	const created = !existsSync(configPath);
+	let source = created ? renderNeonConfig([]) : readFileSync(configPath, "utf8");
+	const changes = [];
+	const alreadyDeclared = [];
+	for (const fn of functions) {
+		const result = editNeonConfig(source, {
+			kind: "function",
+			slug: fn.slug,
+			name: fn.name,
+			source: asRelativeModulePath(relative(dirname(configPath), resolve(targetDir, fn.file)).split("\\").join("/")),
+			env: fn.env,
+			typescript: TYPESCRIPT_EXTENSION.test(configPath)
+		});
+		if (result.changes.length === 0) {
+			alreadyDeclared.push(fn.slug);
+			continue;
+		}
+		source = result.source;
+		changes.push(...result.changes);
+	}
+	return {
+		...created || changes.length > 0 ? { source } : {},
+		created,
+		changes,
+		alreadyDeclared
+	};
+};
+const planEnvExample = (projectRoot, environment) => {
+	const path = join(projectRoot, ".env.example");
+	const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
+	const declared = new Set(Object.keys(existing ? readEnvFile(path) : {}));
+	const missing = environment.filter(({ name }) => !declared.has(name));
+	if (missing.length === 0) return {
+		path,
+		added: []
+	};
+	const block = missing.map(({ name, description }) => `# ${description}\n${name}=\n`).join("\n");
+	return {
+		path,
+		contents: `${existing}${existing === "" ? "" : existing.endsWith("\n") ? "\n" : "\n\n"}${block}`,
+		added: missing.map(({ name }) => name)
+	};
+};
+//#endregion
+export { collidingFiles, operationsFromFlags, planConfigRegistration, planEnvExample, planScaffold, writeScaffold };

package/dist/functions/source.js

@@ -0,0 +1,141 @@
+import { MAX_FILE_BYTES, MAX_JSON_BYTES, MAX_TOTAL_BYTES, isContainedRelativePath, parseRegistryIndex, parseTemplateItem } from "./registry.js";
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import { posix, resolve, sep } from "node:path";
+//#region src/functions/source.ts
+const DEFAULT_REGISTRY_URL = "https://neon.com/functions/registry/registry.json";
+const GITHUB_REGISTRY_URL = "https://raw.githubusercontent.com/neondatabase/examples/main/registry/registry.json";
+const REGISTRY_DIR_ENV = "NEON_FUNCTION_REGISTRY_DIR";
+const REGISTRY_URL_ENV = "NEON_FUNCTION_REGISTRY_URL";
+const REGISTRY_TIMEOUT_MS = 1e4;
+const LOOPBACK_HOSTS = /* @__PURE__ */ new Set([
+	"localhost",
+	"127.0.0.1",
+	"[::1]"
+]);
+var RegistryError = class extends Error {
+	constructor(message, status) {
+		super(message);
+		this.name = "RegistryError";
+		if (status !== void 0) this.status = status;
+	}
+};
+const resolveRegistrySource = (env = process.env, cwd = process.cwd(), defaultUrl = DEFAULT_REGISTRY_URL) => {
+	const dir = env[REGISTRY_DIR_ENV];
+	if (dir) return {
+		kind: "dir",
+		dir: resolve(cwd, dir)
+	};
+	const raw = env["NEON_FUNCTION_REGISTRY_URL"] || defaultUrl;
+	if (!URL.canParse(raw)) throw new RegistryError(`${REGISTRY_URL_ENV} is not a URL: ${raw}`);
+	const url = new URL(raw);
+	if (url.protocol !== "https:" && !(url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname))) throw new RegistryError(`${REGISTRY_URL_ENV} must be an https:// URL, got ${raw}`);
+	return {
+		kind: "url",
+		url
+	};
+};
+const describeRegistrySource = (source) => source.kind === "dir" ? source.dir : source.url.href;
+const tooLarge = (path, limit) => new RegistryError(`Registry file ${path} is larger than the ${limit}-byte limit.`);
+const dirReader = (dir) => {
+	let root;
+	return async (relativePath, limit) => {
+		try {
+			root ??= realpathSync(dir);
+		} catch {
+			throw new RegistryError(`${REGISTRY_DIR_ENV} points at ${dir}, which does not exist.`);
+		}
+		let path;
+		try {
+			path = realpathSync(resolve(root, relativePath));
+		} catch {
+			throw new RegistryError(`Registry file ${relativePath} not found in ${dir}.`);
+		}
+		if (!path.startsWith(root + sep)) throw new RegistryError(`Registry file ${relativePath} resolves outside ${dir}.`);
+		if (statSync(path).size > limit) throw tooLarge(relativePath, limit);
+		return readFileSync(path, "utf8");
+	};
+};
+const urlReader = (index) => {
+	const base = new URL(".", index);
+	return async (relativePath, limit) => {
+		const url = new URL(relativePath, base);
+		if (url.origin !== base.origin || !url.pathname.startsWith(base.pathname)) throw new RegistryError(`Registry file ${relativePath} resolves outside ${base.href}.`);
+		let response;
+		try {
+			response = await fetch(url, {
+				redirect: "error",
+				signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS)
+			});
+		} catch {
+			throw new RegistryError(`Could not reach the Function Registry at ${url.href}. Check your connection, or set ${REGISTRY_DIR_ENV} to a local copy.`);
+		}
+		if (!response.ok) throw new RegistryError(`The Function Registry answered ${response.status} for ${url.href}.`, response.status);
+		if (Number(response.headers.get("content-length")) > limit) throw tooLarge(relativePath, limit);
+		const text = await response.text();
+		if (Buffer.byteLength(text, "utf8") > limit) throw tooLarge(relativePath, limit);
+		return text;
+	};
+};
+const templateSourcePaths = (template) => template.operations?.map((operation) => operation.source) ?? ["functions/index.ts"];
+const INDEX_FILE = "registry.json";
+const openRegistry = async (source, { primary = DEFAULT_REGISTRY_URL, fallback = GITHUB_REGISTRY_URL, env = process.env } = {}) => {
+	if (source) return openRegistryAt(source);
+	const resolved = resolveRegistrySource(env, process.cwd(), primary);
+	if (resolved.kind !== "url" || resolved.url.href !== new URL(primary).href) return openRegistryAt(resolved);
+	const github = {
+		kind: "url",
+		url: new URL(fallback)
+	};
+	try {
+		return await openRegistryAt(resolved, github);
+	} catch (error) {
+		if (!(error instanceof RegistryError)) throw error;
+		return openRegistryAt(github);
+	}
+};
+const readerFor = (source) => source.kind === "dir" ? dirReader(source.dir) : urlReader(source.url);
+const withStaleIndexHint = (read, index, files) => async (path, limit) => {
+	try {
+		return await read(path, limit);
+	} catch (error) {
+		if (!(error instanceof RegistryError) || error.status !== 404) throw error;
+		throw new RegistryError(`${error.message} The index from ${describeRegistrySource(index)} is cached and may still list a template that moved or was removed. Try again in a few minutes, or set ${REGISTRY_URL_ENV}=${describeRegistrySource(files)} to read the current index.`, 404);
+	}
+};
+const openRegistryAt = async (source, files = source) => {
+	const read = readerFor(source);
+	const readFile = files === source ? read : withStaleIndexHint(readerFor(files), source, files);
+	const indexPath = source.kind === "dir" ? INDEX_FILE : posix.basename(source.url.pathname);
+	const parse = (path, text, fn) => {
+		try {
+			return fn(text);
+		} catch (error) {
+			throw new RegistryError(`Invalid registry file ${path}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	};
+	const entries = parse(indexPath, await read(indexPath, MAX_JSON_BYTES), parseRegistryIndex);
+	const load = async (entry) => {
+		if (!entry.path || !isContainedRelativePath(entry.path)) throw new RegistryError(`Template "${entry.id}" has no valid path.`);
+		const template = parse(entry.path, await readFile(entry.path, MAX_JSON_BYTES), (text) => parseTemplateItem(text, entry.id));
+		const dir = posix.dirname(entry.path);
+		const sources = /* @__PURE__ */ new Map();
+		let total = 0;
+		for (const path of templateSourcePaths(template)) {
+			if (!isContainedRelativePath(path)) throw new RegistryError(`Template "${entry.id}" references an unsafe path: ${path}`);
+			const text = await readFile(dir === "." ? path : posix.join(dir, path), Math.min(MAX_FILE_BYTES, MAX_TOTAL_BYTES - total));
+			total += Buffer.byteLength(text, "utf8");
+			sources.set(path, text);
+		}
+		return {
+			template,
+			sources
+		};
+	};
+	return {
+		source,
+		entries,
+		load
+	};
+};
+//#endregion
+export { DEFAULT_REGISTRY_URL, GITHUB_REGISTRY_URL, REGISTRY_DIR_ENV, REGISTRY_URL_ENV, RegistryError, describeRegistrySource, openRegistry, resolveRegistrySource, templateSourcePaths };

package/dist/test_utils/registry.js

@@ -0,0 +1,6 @@
+import { fileURLToPath } from "node:url";
+//#region src/test_utils/registry.ts
+const REGISTRY_SCHEMAS_DIR = fileURLToPath(new URL("../functions/schemas", import.meta.url));
+const FIXTURE_REGISTRY_DIR = fileURLToPath(new URL("../../tests/function-registry", import.meta.url));
+//#endregion
+export { FIXTURE_REGISTRY_DIR, REGISTRY_SCHEMAS_DIR };

package/dist/utils/agent_picker.js

@@ -1,9 +1,9 @@
-import { isCi } from "../env.js";
+import { isInteractiveTerminal } from "../env.js";
 import { getAgentDisplayName, resolveAddMcpAgentId, uniqueAgentIds } from "../mcp/agents.js";
 import prompts from "prompts";
 //#region src/utils/agent_picker.ts
 var AgentSelectionSkipped = class extends Error {};
-const canPickAgentsInteractively = () => !isCi() && Boolean(process.stdout.isTTY) && Boolean(process.stdin.isTTY);
+const canPickAgentsInteractively = () => isInteractiveTerminal();
 const restoreCursorOnAbort = (exit) => (state) => {
 	if (state.aborted) {
 		process.stdout.write("\x1B[?25h");

package/dist/utils/enrichers.js

@@ -1,5 +1,5 @@
 import { isNeonApiError, messageFromBody } from "../api.js";
-import { isConfigAdd, isConfigInit, isCurrentBranchProbe } from "../context.js";
+import { isConfigAdd, isConfigInit, isCurrentBranchProbe, isFunctionsTemplateCommand } from "../context.js";
 import { looksLikeBranchId } from "./formats.js";
 //#region src/utils/enrichers.ts
 const BRANCHES_LIST_LIMIT = 100;
@@ -127,6 +127,7 @@ const fillSingleProject = async (props) => {
 	if (isCurrentBranchProbe(props)) return props;
 	if (isConfigInit(props)) return props;
 	if (isConfigAdd(props)) return props;
+	if (isFunctionsTemplateCommand(props)) return props;
 	if (props.projectId) return {
 		...props,
 		projectId: props.projectId

package/dist/utils/function_slug.js

@@ -0,0 +1,7 @@
+//#region src/utils/function_slug.ts
+/** The rule the platform enforces on function slugs, so a bad one fails before any write. */
+const FUNCTION_SLUG_PATTERN = /^[a-z0-9]{1,20}$/;
+const FUNCTION_SLUG_HELP = "Use 1-20 lowercase letters and digits (no hyphens or other characters).";
+const deriveFunctionSlug = (value) => value.toLowerCase().replace(/[^a-z0-9]/g, "").slice(0, 20);
+//#endregion
+export { FUNCTION_SLUG_HELP, FUNCTION_SLUG_PATTERN, deriveFunctionSlug };

package/dist/utils/package_manager.js

@@ -189,6 +189,7 @@ const recommendedCliUpgradeCommand = (modulePath) => {
 const installArgs = (pm, packages, options) => packages?.length ? [
 	pm === "npm" ? "install" : "add",
 	...options?.dev ? ["-D"] : [],
+	...options?.exact ? ["-E"] : [],
 	...packages
 ] : ["install"];
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neon",
-  "version": "8.10.3",
+  "version": "8.11.1",
   "description": "CLI tool for Neon, the cloud backend primitives built around Lakebase Postgres",
   "keywords": [
     "neon",
@@ -70,8 +70,8 @@
     "yaml": "^2.9.0",
     "yargs": "17.7.2",
     "yoctocolors": "^2.1.2",
-    "@neon/realtime": "0.1.2",
     "@neon/config-runtime": "1.10.2",
+    "@neon/realtime": "0.1.2",
     "@neon/sdk": "7.4.0",
     "@neon/config": "1.9.3"
   },
@@ -111,9 +111,9 @@
     "vitest": "^3.0.9",
     "@neon-internals/cli-core": "0.0.0",
     "@neon-internals/env-core": "0.0.34",
+    "@neon/e2e-harness": "0.0.0",
     "@neon/functions": "0.11.0",
-    "@neon/env": "1.6.4",
-    "@neon/e2e-harness": "0.0.0"
+    "@neon/env": "1.6.4"
   },
   "publishConfig": {
     "access": "public",