neon 6.3.0 → 6.4.0

package/README.md

@@ -665,7 +665,37 @@ export default async function hello(): Promise<Response> {
 }
 ```
 
-An existing `neon.ts` (or `hello.ts`) is never overwritten.
+An existing `neon.ts` (or `hello.ts`) is never overwritten. To change one, use `config add`.
+
+### Editing a `neon.ts` (`config add`)
+
+`neon config add` declares one service in the `neon.ts` you already have and leaves the rest of the file (comments, the `branch` closure, formatting) as it was. It is purely local — no auth, no API calls — and creates the starter `neon.ts` first when there is none.
+
+```bash
+neon config add auth                        # auth: true
+neon config add data-api                    # dataApi: true, and auth: true (the default provider needs it)
+neon config add ai-gateway                  # aiGateway: true
+neon config add function sendemail          # functions.sendemail + functions/sendemail.ts
+neon config add function sendemail --name "Send email" --source ./src/send.ts
+neon config add bucket uploads              # buckets.uploads = { access: 'private' }
+neon config add bucket assets --access public_read
+```
+
+Each command prints what it changed and the next step:
+
+```
+$ neon config add function sendemail
+INFO: Created functions/sendemail.ts.
+INFO: Updated neon.ts: added functions.sendemail.
+INFO: Next: `neon dev` to run it locally, `neon config apply` to deploy.
+```
+
+- **Functions** take a slug of 1-20 lowercase letters and digits, the same rule `plan` enforces. The handler file is written first and an existing file is never overwritten, so pointing `--source` at code you already have works. A `.js` `neon.ts` gets a `.js` handler.
+- Enabling a service that `neon.ts` already enables changes nothing and exits 0. Adding a function slug or bucket name that already exists is an error.
+- `--config <path>` edits a specific file; otherwise the closest `neon.ts` above the current directory is used, and the suggested `plan` / `apply` commands repeat the flag.
+- `--no-install` applies when the command had to create `neon.ts`; editing an existing file never installs anything.
+
+`config add` edits the file as text and checks its own output: it re-applies the edit to the result and fails if that is not a no-op. When the file is in a shape it cannot edit safely (a single-line `defineConfig({ auth: true })`, a service declared under `preview`, a value that is not a literal), it changes nothing and prints the exact lines to paste.
 
 Four sub-commands plus two top-level aliases drive it:
 

package/dist/commands/auth.js

@@ -5,7 +5,7 @@ import { log } from "../log.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, isConfigInit, isCurrentBranchProbe, isGitLocalCommand, isInspectDbUrl, isMcpCommand, isMcpOauth, isPluginsCommand, isProfileCommand, isSkillsCommand, isUnfollowedGitHookSync, readContextFile } from "../context.js";
+import { currentContextFile, isAskCommand, isClaimCommand, isConfigAdd, isConfigInit, isCurrentBranchProbe, 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-CvnFEQyd.js";
 import { extendTokenSet } from "../utils/auth.js";
 import { AuthRefreshError, auth, classifyRefreshFailure, refreshToken } from "../auth.js";
@@ -296,6 +296,7 @@ const ensureAuth = async (props) => {
 	if (props._.length === 0 || props.help) return;
 	if (isCurrentBranchProbe(props)) return;
 	if (isConfigInit(props)) return;
+	if (isConfigAdd(props)) return;
 	if (isProfileCommand(props)) return;
 	if (isGitLocalCommand(props)) return;
 	if (isUnfollowedGitHookSync(props)) return;

package/dist/commands/claim.js

@@ -6,8 +6,8 @@ import { applyContext, contextBranch, readContextFile } from "../context.js";
 import { t as credentialInputs } from "../_chunks/auth_selection-pitMFzDe.js";
 import { ClaimableClient, ClaimableServiceError } from "../claimable/api.js";
 import { assertionHasExpired, listClaimableCredentials, readClaimableCredentials, readLinkedClaimableCredentials, removeClaimableCredentials, writeClaimableCredentials } from "../claimable/state.js";
-import { claimableDataApiCreateBody, declaredNeonServices } from "../config_services.js";
 import { NEON_SERVICES, deprecatedServiceMessage, parseServices, servicesFlagValue, servicesOption } from "../neon_services.js";
+import { claimableDataApiCreateBody, declaredNeonServices } from "../config_services.js";
 import { resolveEnvFilePath } from "../env_file.js";
 import { writer } from "../writer.js";
 import { noPassthrough } from "../utils/flags.js";

package/dist/commands/config.js

@@ -4,10 +4,11 @@ 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 { deprecatedServiceMessage, parseServices, servicesFlagValue, servicesOption } from "../neon_services.js";
+import { CONFIG_INIT_NONE_MEANS, CONFIG_INIT_SERVICES, CONFIG_INIT_UNAVAILABLE, FUNCTION_FILENAME, FUNCTION_SLUG, FUNCTION_TEMPLATE, REQUIRED_PACKAGES, renderFunctionSource, renderNeonConfig, renderNeonConfigFromView } from "../config_template.js";
+import { editNeonConfig } from "../config_edit.js";
 import { toNeonConfigView } from "../config_format.js";
 import { declaredNeonServices } from "../config_services.js";
-import { deprecatedServiceMessage, parseServices, servicesFlagValue, servicesOption } from "../neon_services.js";
-import { CONFIG_INIT_NONE_MEANS, CONFIG_INIT_SERVICES, CONFIG_INIT_UNAVAILABLE, FUNCTION_FILENAME, FUNCTION_SLUG, FUNCTION_TEMPLATE, REQUIRED_PACKAGES, renderNeonConfig, renderNeonConfigFromView } from "../config_template.js";
 import { loadEnvFileIntoProcess } from "../env_file.js";
 import { writer } from "../writer.js";
 import { fillSingleProject, resolveBranchRef } from "../utils/enrichers.js";
@@ -21,14 +22,16 @@ import { resolveHookEnv, runDeployAfterHook, runDeployBeforeHook } from "../util
 import { pickServicesInteractively } from "../utils/service_picker.js";
 import { zipBundle } from "../utils/zip.js";
 import { autoPullEnvAfterPin } from "./env.js";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { homedir } from "node:os";
 import chalk from "chalk";
 import { packagesToStage, previewGaWarningForConfig, resolveConfig } from "@neon/config";
 import { PushConflictError, apply, assertZipWithinLimits, bundleAsIs, createBranch, describeNativeFinding, enforceLimits, findUndeclaredNativePackages, inspect, isPartialBranchCreateError, loadConfigFromFile as loadConfigFromFile$1, plan, resolveEsbuildEntry, traceNativePackages, zipFunctionBundle } from "@neon/config-runtime";
 //#region src/commands/config.ts
 var config_exports = /* @__PURE__ */ __exportAll({
 	ConfigInstallFailed: () => ConfigInstallFailed,
+	addCmd: () => addCmd,
 	applyCmd: () => applyCmd,
 	applyFlags: () => applyFlags,
 	applyPolicyOnCreate: () => applyPolicyOnCreate,
@@ -213,6 +216,28 @@ const seedFromBranch = async (props) => {
 		branchName: live.branch.name
 	};
 };
+/** Install the config packages the project is missing, or say how to. */
+const ensureConfigPackages = async (cwd, props) => {
+	const run = props.run ?? runCommand;
+	const missing = missingDependencies(cwd);
+	if (missing.length === 0) {
+		if (!props.silent) log.info("%s are already installed.", REQUIRED_PACKAGES.join(" and "));
+		return;
+	}
+	const pm = props.packageManager ?? resolvePackageManager(cwd);
+	const args = installArgs(pm, missing);
+	if (props.install === false) {
+		if (!props.silent) log.info("Install the Neon config packages to use neon.ts: %s", formatInstallCommand(pm, missing));
+		return;
+	}
+	ensureDirectoryGitignored(join(cwd, "node_modules"));
+	if (!props.silent) log.info("Installing %s with %s…", missing.join(", "), pm);
+	if (!await run(pm, args, cwd)) {
+		const command = formatInstallCommand(pm, missing);
+		if (props.requireInstall) throw new ConfigInstallFailed(command);
+		log.warning("Could not install the config packages automatically. Run by hand: %s", command);
+	}
+};
 /**
 * Scaffold a `neon.ts` policy and make sure the Neon config packages are
 * installed, so a project can go straight to `neon config plan` / `apply`.
@@ -220,10 +245,12 @@ const seedFromBranch = async (props) => {
 */
 const initCmd = async (props) => {
 	const cwd = props.cwd ?? process.cwd();
-	const run = props.run ?? runCommand;
 	const existing = neonConfigFilename(cwd);
 	if (existing) {
-		if (!props.silent) log.info("Found an existing %s — leaving it untouched.", existing);
+		if (!props.silent) {
+			log.info("Found an existing %s — leaving it untouched.", existing);
+			if (props.services !== void 0) log.warning("--services was ignored. To declare services in the existing %s, use `%s config add`.", existing, getCliName());
+		}
 	} else if (props.fromBranch) {
 		const { source, seeded, branchName } = await seedFromBranch(props);
 		writeFileSync(join(cwd, "neon.ts"), source);
@@ -240,26 +267,139 @@ const initCmd = async (props) => {
 		}
 		if (services.includes("functions")) scaffoldFunction(cwd);
 	}
-	const missing = missingDependencies(cwd);
-	if (missing.length === 0) {
-		if (!props.silent) log.info("%s are already installed.", REQUIRED_PACKAGES.join(" and "));
-	} else {
-		const pm = props.packageManager ?? resolvePackageManager(cwd);
-		const args = installArgs(pm, missing);
-		if (props.install === false) {
-			if (!props.silent) log.info("Install the Neon config packages to use neon.ts: %s", formatInstallCommand(pm, missing));
-		} else {
-			ensureDirectoryGitignored(join(cwd, "node_modules"));
-			if (!props.silent) log.info("Installing %s with %s…", missing.join(", "), pm);
-			if (!await run(pm, args, cwd)) {
-				const command = formatInstallCommand(pm, missing);
-				if (props.requireInstall) throw new ConfigInstallFailed(command);
-				log.warning("Could not install the config packages automatically. Run by hand: %s", command);
+	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)$/;
+/**
+* The nearest neon.ts, found the way the config loader finds it: walk up from `start`, stop
+* at the first directory holding `.git` (or at the home directory).
+*/
+const findNeonConfigUpward = (start) => {
+	let dir = resolve(start);
+	for (;;) {
+		const name = neonConfigFilename(dir);
+		if (name) return join(dir, name);
+		if (existsSync(join(dir, ".git")) || dir === homedir()) return void 0;
+		const parent = dirname(dir);
+		if (parent === dir) return void 0;
+		dir = parent;
+	}
+};
+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
+* carry it, or they would act on whichever `neon.ts` a walk up from cwd finds instead.
+*/
+const planAdd = (target, configPath, explicitConfig) => {
+	const language = TYPESCRIPT_EXTENSION.test(configPath) ? "ts" : "js";
+	const cli = getCliName();
+	const flag = explicitConfig ? ` --config ${shellQuote(explicitConfig)}` : "";
+	const provision = `Next: \`${cli} config plan${flag}\` to preview, \`${cli} config apply${flag}\` to provision.`;
+	switch (target.kind) {
+		case "service": return {
+			edit: {
+				kind: "service",
+				service: target.service
+			},
+			next: provision
+		};
+		case "bucket":
+			if (target.name.length < 1 || target.name.length > 255) throw new Error("A bucket name must be 1-255 characters.");
+			if (target.name === "__proto__") throw new Error("\"__proto__\" cannot be used as a bucket name.");
+			return {
+				edit: {
+					kind: "bucket",
+					name: target.name,
+					access: target.access ?? "private"
+				},
+				next: provision
+			};
+		case "function": {
+			if (!FUNCTION_SLUG_PATTERN.test(target.slug)) {
+				const suggestion = target.slug.toLowerCase().replace(/[^a-z0-9]/g, "").slice(0, 20);
+				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.`);
+			const source = asRelativeModulePath(target.source ?? `functions/${target.slug}.${language}`);
+			return {
+				edit: {
+					kind: "function",
+					slug: target.slug,
+					name: target.name ?? target.slug,
+					source
+				},
+				sourceFile: resolve(dirname(configPath), source),
+				next: explicitConfig ? `Next: \`${cli} config apply${flag}\` to deploy.` : `Next: \`${cli} dev\` to run it locally, \`${cli} config apply\` to deploy.`
+			};
 		}
 	}
-	if (!props.silent) log.info("Next: edit neon.ts, then run `neon config plan` to preview and `neon config apply`.");
 };
+/**
+* Declare a service, function, or bucket in the project's `neon.ts` with a text edit that
+* leaves the rest of the file alone, creating the file (and installing the config packages)
+* when the project has none. Local only, like `config init`.
+*/
+const addCmd = async (props) => {
+	const cwd = props.cwd ?? process.cwd();
+	let existing;
+	if (props.config) {
+		existing = resolve(cwd, props.config);
+		if (!existsSync(existing)) throw new Error(`--config ${props.config} does not exist.`);
+	} else existing = findNeonConfigUpward(cwd);
+	const configPath = existing ?? join(cwd, "neon.ts");
+	const shown = (path) => relative(cwd, path) || path;
+	const plan = planAdd(props.target, configPath, props.config);
+	const { source, changes } = editNeonConfig(existing ? readFileSync(existing, "utf8") : renderNeonConfig([]), plan.edit);
+	if (changes.length === 0) {
+		if (props.target.kind === "service") {
+			log.info("%s already enables that; nothing to change.", shown(configPath));
+			return;
+		}
+		throw new Error(`${shown(configPath)} already declares ${props.target.kind} "${props.target.kind === "function" ? props.target.slug : props.target.name}". Edit it there, or pick another name.`);
+	}
+	if (plan.sourceFile) {
+		if (existsSync(plan.sourceFile)) log.info("Found an existing %s — leaving it untouched.", shown(plan.sourceFile));
+		else {
+			mkdirSync(dirname(plan.sourceFile), { recursive: true });
+			const slug = props.target.kind === "function" ? props.target.slug : "";
+			writeFileSync(plan.sourceFile, renderFunctionSource(slug, TYPESCRIPT_EXTENSION.test(plan.sourceFile) ? "ts" : "js"));
+			log.info("Created %s.", shown(plan.sourceFile));
+		}
+	}
+	writeFileSync(configPath, source);
+	log.info("%s %s: %s.", existing ? "Updated" : "Created", shown(configPath), changes.join(", "));
+	if (!existing) await ensureConfigPackages(dirname(configPath), props);
+	log.info("%s", plan.next);
+};
+/**
+* Options every `config add` sub-command takes. `--project-id` and `--branch` are inherited
+* from `config` but mean nothing to a command that never leaves the working tree, so they are
+* hidden from its help.
+*/
+const addSharedOptions = (yargs) => yargs.strict().options({
+	"project-id": { hidden: true },
+	branch: { hidden: true },
+	config: {
+		describe: "Path to the neon.ts to edit (defaults to walking up from cwd; created in cwd when there is none)",
+		type: "string"
+	},
+	install: {
+		describe: "Install @neon/config and @neon/env when creating neon.ts. On by default; use --no-install to just print the command.",
+		type: "boolean",
+		default: true
+	}
+});
+/** The `config add` props for a sub-command's parsed flags. */
+const addProps = (args, target) => ({
+	target,
+	install: args.install,
+	...args.config !== void 0 ? { config: args.config } : {}
+});
 const command = "config";
 const describe = "Manage a branch with a neon.ts policy";
 const builder = (argv) => argv.usage("$0 config <sub-command> [options]").options({
@@ -296,7 +436,47 @@ const builder = (argv) => argv.usage("$0 config <sub-command> [options]").option
 	...envFlag,
 	...applyFlags,
 	...envPullFlag
-}), (args) => applyCmd(args)).command("init", "Scaffold a neon.ts policy and install the Neon config packages", (yargs) => yargs.options({
+}), (args) => applyCmd(args)).command("add", "Add a service, function, or bucket to neon.ts (creates it if missing)", (yargs) => yargs.command("auth", "Enable Neon Auth (auth: true)", addSharedOptions, (args) => addCmd(addProps(args, {
+	kind: "service",
+	service: "auth"
+}))).command("data-api", "Enable the Data API (dataApi: true) and Neon Auth, which the default provider requires", addSharedOptions, (args) => addCmd(addProps(args, {
+	kind: "service",
+	service: "data-api"
+}))).command("ai-gateway", "Enable the AI Gateway (aiGateway: true)", addSharedOptions, (args) => addCmd(addProps(args, {
+	kind: "service",
+	service: "ai-gateway"
+}))).command("function <slug>", "Declare a Neon Function and create its handler file", (yargs) => addSharedOptions(yargs).example("$0 config add function sendemail", "Creates functions/sendemail.ts and declares it").example("$0 config add function sendemail --source src/send.ts", "Declares an existing handler").positional("slug", {
+	describe: "Function slug: 1-20 lowercase letters and digits",
+	type: "string",
+	demandOption: true
+}).options({
+	name: {
+		describe: "Display name. Defaults to the slug",
+		type: "string"
+	},
+	source: {
+		describe: "Handler file, relative to neon.ts. Defaults to functions/<slug>.ts. Created when missing, left alone when it exists",
+		type: "string"
+	}
+}), (args) => addCmd(addProps(args, {
+	kind: "function",
+	slug: args.slug,
+	...args.name !== void 0 ? { name: args.name } : {},
+	...args.source !== void 0 ? { source: args.source } : {}
+}))).command("bucket <name>", "Declare an Object Storage bucket", (yargs) => addSharedOptions(yargs).example("$0 config add bucket assets --access public_read", "Declares a bucket that allows anonymous reads").positional("name", {
+	describe: "Bucket name",
+	type: "string",
+	demandOption: true
+}).options({ access: {
+	describe: "Anonymous access: private requires credentials, public_read allows anonymous reads",
+	type: "string",
+	choices: ["private", "public_read"],
+	default: "private"
+} }), (args) => addCmd(addProps(args, {
+	kind: "bucket",
+	name: args.name,
+	access: args.access
+}))).demandCommand(1, "Specify what to add: auth, data-api, ai-gateway, function, or bucket.")).command("init", "Scaffold a neon.ts policy and install the Neon config packages", (yargs) => yargs.options({
 	install: {
 		describe: "Install @neon/config and @neon/env if they're missing. On by default; use --no-install to just print the command.",
 		type: "boolean",
@@ -803,4 +983,4 @@ const createBranchFromPolicyOnCheckout = async (props) => {
 	}
 };
 //#endregion
-export { ConfigInstallFailed, applyCmd, applyFlags, applyPolicyOnCreate, builder, command, createBranchFromPolicyOnCheckout, describe, envFlag, envPullFlag, handler, hasNeonConfigFile, initCmd, neonConfigFilename, planCmd, status, config_exports as t };
+export { ConfigInstallFailed, addCmd, applyCmd, applyFlags, applyPolicyOnCreate, builder, command, createBranchFromPolicyOnCheckout, describe, envFlag, envPullFlag, handler, hasNeonConfigFile, initCmd, neonConfigFilename, planCmd, status, config_exports as t };

package/dist/config_edit.js

@@ -0,0 +1,237 @@
+import { SourceScanError, classify, entryObject, findConfigObject, findEntry, isCodeAt, isCommentAt, lineIndent, lineStart, scanObject } from "./config_source.js";
+import { renderKey } from "./config_template.js";
+//#region src/config_edit.ts
+/**
+* Edits to an existing `neon.ts`, applied as text splices so comments, formatting, and every
+* property the edit does not name survive untouched. The file is never regenerated.
+*
+* Each edit either declares something new, flips a disabled toggle on, or reports that the
+* 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.
+*/
+var ConfigEditError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ConfigEditError";
+	}
+};
+/** Top-level keys in the order the starter policy writes them. New keys land in this order. */
+const KEY_ORDER = [
+	"auth",
+	"dataApi",
+	"aiGateway",
+	"functions",
+	"buckets",
+	"triggers",
+	"preview",
+	"branch",
+	"experimental"
+];
+const keyRank = (key) => key === void 0 ? -1 : KEY_ORDER.indexOf(key);
+const unsupported = (reason, snippet) => {
+	throw new ConfigEditError(`Cannot edit this neon.ts automatically: ${reason}\nDeclare it by hand:\n\n${snippet.map((line) => `  ${line}`).join("\n")}`);
+};
+const parse = (source) => {
+	try {
+		const kinds = classify(source);
+		const root = assertPlain(scanObject(source, kinds, findConfigObject(source, kinds)));
+		const first = root.entries[0];
+		const base = lineIndent(source, root.open);
+		const firstIndent = first ? lineIndent(source, first.start) : base;
+		const unit = firstIndent.startsWith(base) && firstIndent.length > base.length ? firstIndent.slice(base.length) : "  ";
+		return {
+			source,
+			kinds,
+			root,
+			eol: source.includes("\r\n") ? "\r\n" : "\n",
+			unit
+		};
+	} catch (error) {
+		if (error instanceof SourceScanError) throw new ConfigEditError(`Cannot edit this neon.ts automatically: ${error.message}.`);
+		throw error;
+	}
+};
+/**
+* A spread, a computed key, or a repeated key can override the property an edit just wrote,
+* so the effective value cannot be read from the text.
+*/
+const assertPlain = (scan) => {
+	const seen = /* @__PURE__ */ new Set();
+	for (const entry of scan.entries) {
+		if (entry.key === void 0 || seen.has(entry.key)) throw new ConfigEditError("Cannot edit this neon.ts automatically: an object it edits has a spread, computed, or repeated property that could override the edit.");
+		seen.add(entry.key);
+	}
+	return scan;
+};
+/** The object literal `entry` holds, or `undefined` when its value is anything else. */
+const objectOf = (parsed, entry) => {
+	const scan = entry.keyed ? entryObject(parsed.source, parsed.kinds, entry) : void 0;
+	return scan && assertPlain(scan);
+};
+const startsLine = (source, index) => source.slice(lineStart(source, index), index).trim() === "";
+/**
+* Where a new entry goes, as a splice into `parsed.source`. `before` places it above that
+* entry (and above the comment lines that describe it); without it the entry is appended.
+*/
+const insertEntry = (parsed, scan, lines, snippet, before) => {
+	const { source, kinds, eol, unit } = parsed;
+	const baseIndent = lineIndent(source, scan.open);
+	const first = scan.entries[0];
+	if (!first) {
+		if (source.slice(scan.open + 1, scan.close).trim() !== "") return unsupported("the object it goes in holds only comments.", snippet);
+		const indent = baseIndent + unit;
+		return source.slice(0, scan.open + 1) + eol + lines.map((line) => indent + line).join(eol) + eol + baseIndent + source.slice(scan.close);
+	}
+	const last = scan.entries[scan.entries.length - 1];
+	if (!startsLine(source, first.start) || !source.slice(last.end, scan.close).includes("\n")) return unsupported("the object it goes in is not laid out one property per line.", snippet);
+	const indent = lineIndent(source, first.start);
+	if (before) {
+		if (!startsLine(source, before.start)) return unsupported("a property sharing its line with another one.", snippet);
+		let at = lineStart(source, before.start);
+		while (at > 0) {
+			const previous = lineStart(source, at - 1);
+			const text = source.slice(previous, at);
+			const marker = previous + text.search(/\S|$/);
+			if (previous <= scan.open || !text.trim().startsWith("//") || !isCommentAt(kinds, marker)) break;
+			at = previous;
+		}
+		return source.slice(0, at) + lines.map((line) => indent + line + eol).join("") + source.slice(at);
+	}
+	let lineEnd = source.indexOf("\n", last.end);
+	if (source[lineEnd - 1] === "\r") lineEnd--;
+	let hasComma = false;
+	for (let i = last.end; i < scan.close; i++) {
+		if (!isCodeAt(kinds, i) || source[i] !== ",") continue;
+		if (i >= lineEnd) return unsupported("a trailing comma on a line of its own.", snippet);
+		hasComma = true;
+	}
+	return source.slice(0, last.end) + (hasComma ? "" : ",") + source.slice(last.end, lineEnd) + eol + lines.map((line) => indent + line).join(eol) + source.slice(lineEnd);
+};
+/** The first top-level entry that belongs after `key` in the starter policy's order. */
+const entryAfter = (parsed, key) => parsed.root.entries.find((entry) => keyRank(entry.key) > keyRank(key));
+/**
+* `preview` still accepts `aiGateway`, `functions`, and `buckets`, and declaring the same key
+* in both places fails validation. Adding to the other home would break the file.
+*/
+const assertNotUnderPreview = (parsed, key, snippet) => {
+	const preview = findEntry(parsed.root, "preview");
+	if (!preview) return;
+	const scan = objectOf(parsed, preview);
+	if (!scan) {
+		unsupported(`preview is not an object literal, so it may already declare ${key}.`, snippet);
+		return;
+	}
+	if (findEntry(scan, key)) unsupported(`${key} is declared under the deprecated \`preview\` block. Lift it to the top level first.`, snippet);
+};
+const readToggle = (parsed, entry, key, snippet) => {
+	const { source } = parsed;
+	const value = source.slice(entry.valueStart, entry.valueEnd);
+	if (entry.keyed && value === "true") return { on: true };
+	if (entry.keyed && value === "false") return {
+		on: false,
+		span: [entry.valueStart, entry.valueEnd],
+		path: key
+	};
+	const object = objectOf(parsed, entry);
+	if (!object) return unsupported(`${key} is set to an expression, not true or false.`, snippet);
+	const enabled = findEntry(object, "enabled");
+	if (!enabled) return { on: true };
+	const flag = source.slice(enabled.valueStart, enabled.valueEnd);
+	if (enabled.keyed && flag === "true") return { on: true };
+	if (enabled.keyed && flag === "false") return {
+		on: false,
+		span: [enabled.valueStart, enabled.valueEnd],
+		path: `${key}.enabled`
+	};
+	return unsupported(`${key}.enabled is set to an expression, not true or false.`, snippet);
+};
+const setToggle = (parsed, key) => {
+	const snippet = [`${key}: true,`];
+	if (key === "aiGateway") assertNotUnderPreview(parsed, key, snippet);
+	const entry = findEntry(parsed.root, key);
+	if (!entry) return {
+		source: insertEntry(parsed, parsed.root, snippet, snippet, entryAfter(parsed, key)),
+		change: `added ${key}: true`
+	};
+	const toggle = readToggle(parsed, entry, key, snippet);
+	if (toggle.on) return { source: parsed.source };
+	const [from, to] = toggle.span;
+	return {
+		source: parsed.source.slice(0, from) + "true" + parsed.source.slice(to),
+		change: `set ${toggle.path}: false → true`
+	};
+};
+/**
+* Whether `dataApi` verifies a third-party IdP, in which case it does not need Neon Auth. An
+* `authProvider` that is neither literal is refused rather than assumed to be Neon's.
+*/
+const dataApiIsExternal = (parsed) => {
+	const entry = findEntry(parsed.root, "dataApi");
+	const object = entry ? objectOf(parsed, entry) : void 0;
+	const provider = object ? findEntry(object, "authProvider") : void 0;
+	if (!provider) return false;
+	const value = parsed.source.slice(provider.valueStart, provider.valueEnd).replace(/\s+as\s+const$/, "");
+	if (provider.keyed && /^["']external["']$/.test(value)) return true;
+	if (provider.keyed && /^["']neon["']$/.test(value)) return false;
+	return unsupported("dataApi.authProvider is set to an expression.", ["auth: true,", "dataApi: true,"]);
+};
+/** A named entry (a function or a bucket) inside `functions` / `buckets`. */
+const addNamed = (parsed, container, name, entryLines) => {
+	const block = [
+		`${container}: {`,
+		...entryLines.map((line) => parsed.unit + line),
+		"},"
+	];
+	assertNotUnderPreview(parsed, container, block);
+	const entry = findEntry(parsed.root, container);
+	if (!entry) return {
+		source: insertEntry(parsed, parsed.root, block, block, entryAfter(parsed, container)),
+		change: `added ${container}.${name}`
+	};
+	const object = objectOf(parsed, entry);
+	if (!object) return unsupported(`${container} is not an object literal.`, block);
+	if (findEntry(object, name)) return { source: parsed.source };
+	return {
+		source: insertEntry(parsed, object, entryLines, block),
+		change: `added ${container}.${name}`
+	};
+};
+const apply = (source, edit) => {
+	const steps = [];
+	let current = source;
+	const run = (build) => {
+		const step = build(parse(current));
+		current = step.source;
+		steps.push(step);
+	};
+	switch (edit.kind) {
+		case "service":
+			if (edit.service === "auth") run((parsed) => setToggle(parsed, "auth"));
+			else if (edit.service === "ai-gateway") run((parsed) => setToggle(parsed, "aiGateway"));
+			else {
+				if (!dataApiIsExternal(parse(current))) run((parsed) => setToggle(parsed, "auth"));
+				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)} },`]));
+			break;
+		case "bucket": run((parsed) => addNamed(parsed, "buckets", edit.name, [`${renderKey(edit.name)}: { access: ${JSON.stringify(edit.access)} },`]));
+	}
+	return {
+		source: current,
+		changes: steps.flatMap((step) => step.change ? [step.change] : [])
+	};
+};
+/**
+* Apply `edit` to the text of a `neon.ts`. The result is re-read before it is returned: a
+* splice the scanner cannot find its own edit in is a bug in the splice, and it throws
+* instead of handing back a file that does not declare what was asked for.
+*/
+const editNeonConfig = (source, edit) => {
+	const result = apply(source, edit);
+	if (result.changes.length > 0 && apply(result.source, edit).changes.length > 0) throw new ConfigEditError("Editing neon.ts would not produce a file that declares the requested change. Nothing was written.");
+	return result;
+};
+//#endregion
+export { ConfigEditError, editNeonConfig };

package/dist/config_source.js

@@ -0,0 +1,270 @@
+//#region src/config_source.ts
+/**
+* A scanner for the shape of a `neon.ts` file, just deep enough to find the config object
+* literal and the spans of its properties, so an edit can splice text into the file and leave
+* everything else byte-for-byte alone.
+*
+* It is not a JavaScript parser. It classifies every character as code, comment, or literal
+* (string, template text, regex), matches brackets over the code characters, and splits an
+* object literal on its top-level commas. Anything it cannot place with confidence throws
+* {@link SourceScanError}; callers turn that into "edit it by hand" rather than guessing.
+*/
+var SourceScanError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "SourceScanError";
+	}
+};
+const CODE = 0;
+const COMMENT = 1;
+const LITERAL = 2;
+const REGEX_MAY_FOLLOW = /* @__PURE__ */ new Set([..."(,=:[!&|?{};+-*%<>~^"]);
+const REGEX_KEYWORDS = /* @__PURE__ */ new Set([
+	"return",
+	"typeof",
+	"case",
+	"in",
+	"of",
+	"delete",
+	"void",
+	"throw",
+	"new",
+	"else",
+	"do",
+	"yield",
+	"await"
+]);
+const isIdentChar = (char) => /[\w$]/.test(char);
+const isSpace = (char) => /\s/.test(char);
+const unterminated = (what, at) => new SourceScanError(`unterminated ${what} at offset ${at}`);
+/** Whether the `/` at `index` opens a regex literal rather than dividing. */
+const opensRegex = (source, kinds, index) => {
+	let prev = index - 1;
+	while (prev >= 0 && (isSpace(source[prev]) || kinds[prev] === COMMENT)) prev--;
+	if (prev < 0) return true;
+	if (kinds[prev] === LITERAL) return false;
+	const char = source[prev];
+	if (isIdentChar(char)) {
+		let start = prev;
+		while (start > 0 && isIdentChar(source[start - 1])) start--;
+		return REGEX_KEYWORDS.has(source.slice(start, prev + 1));
+	}
+	return REGEX_MAY_FOLLOW.has(char);
+};
+/** Classify every character of `source` as code, comment, or literal. */
+const classify = (source) => {
+	const kinds = new Uint8Array(source.length);
+	const length = source.length;
+	const templateDepths = [];
+	const mark = (from, to, kind) => {
+		kinds.fill(kind, from, to);
+	};
+	const scanTemplateText = (from) => {
+		let i = from + 1;
+		while (i < length) if (source[i] === "\\") i += 2;
+		else if (source[i] === "`") {
+			mark(from, i + 1, LITERAL);
+			return i + 1;
+		} else if (source[i] === "$" && source[i + 1] === "{") {
+			mark(from, i + 2, LITERAL);
+			templateDepths.push({
+				start: i,
+				depth: 0
+			});
+			return i + 2;
+		} else i++;
+		throw unterminated("template literal", from);
+	};
+	let i = 0;
+	while (i < length) {
+		const char = source[i];
+		const next = source[i + 1];
+		if (char === "/" && next === "/") {
+			const newline = source.indexOf("\n", i);
+			const end = newline === -1 ? length : newline;
+			mark(i, end, COMMENT);
+			i = end;
+		} else if (char === "/" && next === "*") {
+			const close = source.indexOf("*/", i + 2);
+			if (close === -1) throw unterminated("block comment", i);
+			mark(i, close + 2, COMMENT);
+			i = close + 2;
+		} else if (char === "\"" || char === "'") {
+			let j = i + 1;
+			while (j < length && source[j] !== char) {
+				if (source[j] === "\n") throw unterminated("string", i);
+				j += source[j] === "\\" ? 2 : 1;
+			}
+			if (j >= length) throw unterminated("string", i);
+			mark(i, j + 1, LITERAL);
+			i = j + 1;
+		} else if (char === "`") i = scanTemplateText(i);
+		else if (char === "/") {
+			if (!opensRegex(source, kinds, i)) {
+				i++;
+				continue;
+			}
+			let j = i + 1;
+			let inClass = false;
+			while (j < length) {
+				const c = source[j];
+				if (c === "\n") throw unterminated("regular expression", i);
+				if (c === "\\") {
+					j += 2;
+					continue;
+				}
+				if (c === "[") inClass = true;
+				else if (c === "]") inClass = false;
+				else if (c === "/" && !inClass) break;
+				j++;
+			}
+			if (j >= length) throw unterminated("regular expression", i);
+			j++;
+			while (j < length && /[a-z]/i.test(source[j])) j++;
+			mark(i, j, LITERAL);
+			i = j;
+		} else if (char === "{" && templateDepths.length > 0) {
+			templateDepths[templateDepths.length - 1].depth++;
+			i++;
+		} else if (char === "}" && templateDepths.length > 0) {
+			const top = templateDepths[templateDepths.length - 1];
+			if (top.depth === 0) {
+				templateDepths.pop();
+				mark(top.start, i, LITERAL);
+				i = scanTemplateText(i);
+			} else {
+				top.depth--;
+				i++;
+			}
+		} else i++;
+	}
+	if (templateDepths.length > 0) throw unterminated("template expression", length);
+	return kinds;
+};
+const isTrivia = (source, kinds, index) => isSpace(source[index]) || kinds[index] === COMMENT;
+const skipTrivia = (source, kinds, from, to) => {
+	let i = from;
+	while (i < to && isTrivia(source, kinds, i)) i++;
+	return i;
+};
+const trimTriviaEnd = (source, kinds, from, to) => {
+	let i = to;
+	while (i > from && isTrivia(source, kinds, i - 1)) i--;
+	return i;
+};
+const readEntry = (source, kinds, from, to) => {
+	const start = skipTrivia(source, kinds, from, to);
+	if (start >= to) return void 0;
+	const end = trimTriviaEnd(source, kinds, start, to);
+	const other = (key) => ({
+		key,
+		keyed: false,
+		start,
+		end,
+		valueStart: end,
+		valueEnd: end
+	});
+	let key;
+	let afterKey;
+	if (kinds[start] === LITERAL && (source[start] === "\"" || source[start] === "'")) {
+		let close = start;
+		while (close < end && kinds[close] === LITERAL) close++;
+		const inner = source.slice(start + 1, close - 1);
+		if (inner.includes("\\")) return other();
+		key = inner;
+		afterKey = close;
+	} else {
+		const ident = /^[A-Za-z_$][\w$]*/.exec(source.slice(start, end));
+		if (kinds[start] !== CODE || ident === null) return other();
+		key = ident[0];
+		afterKey = start + key.length;
+	}
+	const colon = skipTrivia(source, kinds, afterKey, end);
+	if (colon >= end || source[colon] !== ":" || kinds[colon] !== CODE) return other(key);
+	const valueStart = skipTrivia(source, kinds, colon + 1, end);
+	return {
+		key,
+		keyed: true,
+		start,
+		end,
+		valueStart,
+		valueEnd: end
+	};
+};
+/** Scan the object literal whose `{` is at `open`. */
+const scanObject = (source, kinds, open) => {
+	if (source[open] !== "{" || kinds[open] !== CODE) throw new SourceScanError(`expected an object literal at offset ${open}`);
+	const entries = [];
+	let depth = 0;
+	let entryStart = open + 1;
+	for (let i = open + 1; i < source.length; i++) {
+		if (kinds[i] !== CODE) continue;
+		const char = source[i];
+		if (char === "{" || char === "[" || char === "(") depth++;
+		else if (char === "}" || char === "]" || char === ")") {
+			if (depth > 0) {
+				depth--;
+				continue;
+			}
+			if (char !== "}") throw new SourceScanError(`unbalanced "${char}" at offset ${i}`);
+			const last = readEntry(source, kinds, entryStart, i);
+			if (last) entries.push(last);
+			return {
+				open,
+				close: i,
+				entries
+			};
+		} else if (char === "," && depth === 0) {
+			const entry = readEntry(source, kinds, entryStart, i);
+			if (entry) entries.push(entry);
+			entryStart = i + 1;
+		}
+	}
+	throw new SourceScanError(`object literal at offset ${open} is never closed`);
+};
+/** The entry named `key`, when the object has one. */
+const findEntry = (scan, key) => scan.entries.find((entry) => entry.key === key);
+/**
+* The object literal an entry's value is, or `undefined` when the value is anything else
+* (`true`, an identifier, `{ … } as const`, a call). Only a value that is exactly one object
+* literal can be edited in place.
+*/
+const entryObject = (source, kinds, entry) => {
+	if (!entry.keyed || source[entry.valueStart] !== "{") return void 0;
+	const scan = scanObject(source, kinds, entry.valueStart);
+	return scan.close + 1 === entry.valueEnd ? scan : void 0;
+};
+/**
+* The index of the `{` holding the policy: the argument of the `defineConfig(` call, or the
+* object a bare `export default { … }` exports. More than one candidate is refused, since
+* the first one in the text is not necessarily the one exported.
+*/
+const findConfigObject = (source, kinds) => {
+	const candidates = [];
+	for (const call of source.matchAll(/\bdefineConfig\s*\(/g)) {
+		if (kinds[call.index] !== CODE) continue;
+		const arg = skipTrivia(source, kinds, call.index + call[0].length, source.length);
+		if (source[arg] !== "{") throw new SourceScanError("defineConfig() is not called with an object literal");
+		candidates.push(arg);
+	}
+	for (const exported of source.matchAll(/\bexport\s+default\s+(?=\{)/g)) if (kinds[exported.index] === CODE) candidates.push(exported.index + exported[0].length);
+	if (candidates.length === 0) throw new SourceScanError("no defineConfig({ … }) call found");
+	if (candidates.length > 1) throw new SourceScanError("found more than one config object, so the exported one is ambiguous");
+	return candidates[0];
+};
+/** Start index of the line containing `index`. */
+const lineStart = (source, index) => source.lastIndexOf("\n", index - 1) + 1;
+/**
+* The whitespace that indents the line containing `index`, whatever else is on that line.
+*/
+const lineIndent = (source, index) => {
+	const start = lineStart(source, index);
+	const indent = /^[ \t]*/.exec(source.slice(start));
+	return indent ? indent[0] : "";
+};
+/** Whether the character at `index` is a comment character. */
+const isCommentAt = (kinds, index) => kinds[index] === COMMENT;
+/** Whether the character at `index` is code (not a comment, string, or regex). */
+const isCodeAt = (kinds, index) => kinds[index] === CODE;
+//#endregion
+export { SourceScanError, classify, entryObject, findConfigObject, findEntry, isCodeAt, isCommentAt, lineIndent, lineStart, scanObject };

package/dist/config_template.js

@@ -186,10 +186,18 @@ ${body}
 * `resolveFetchHandler`), and the bare function is less to read and less to get wrong. It is
 * named rather than anonymous so a project's linter has nothing to say about it, and takes no
 * parameter because a scaffold shipping an unused `req` fails a `noUnusedParameters` project.
+*
+* The name is the slug when that is a usable identifier (a slug may start with a digit or be a
+* reserved word such as `default`), and
+* the return type is dropped for a `.js` config, where it would not parse.
 */
-const FUNCTION_TEMPLATE = `export default async function hello(): Promise<Response> {
+const RESERVED_WORDS = new Set("await break case catch class const continue debugger default delete do else enum export extends false finally for function if import in instanceof new null return super switch this throw true try typeof var void while with yield let static implements interface package private protected public eval arguments".split(" "));
+const renderFunctionSource = (slug, language) => {
+	return `export default async function ${/^[A-Za-z_$][\w$]*$/.test(slug) && !RESERVED_WORDS.has(slug) ? slug : "handler"}()${language === "ts" ? ": Promise<Response>" : ""} {
   return new Response("Hello from Neon Functions");
 }
 `;
+};
+const FUNCTION_TEMPLATE = renderFunctionSource(FUNCTION_SLUG, "ts");
 //#endregion
-export { BUCKET_NAME, CONFIG_INIT_NONE_MEANS, CONFIG_INIT_SERVICES, CONFIG_INIT_UNAVAILABLE, CONFIG_PACKAGE, ENV_PACKAGE, FUNCTION_FILENAME, FUNCTION_NAME, FUNCTION_SLUG, FUNCTION_TEMPLATE, REQUIRED_PACKAGES, renderNeonConfig, renderNeonConfigFromView };
+export { BUCKET_NAME, CONFIG_INIT_NONE_MEANS, CONFIG_INIT_SERVICES, CONFIG_INIT_UNAVAILABLE, CONFIG_PACKAGE, ENV_PACKAGE, FUNCTION_FILENAME, FUNCTION_NAME, FUNCTION_SLUG, FUNCTION_TEMPLATE, REQUIRED_PACKAGES, renderFunctionSource, renderKey, renderNeonConfig, renderNeonConfigFromView };

package/dist/context.js

@@ -37,6 +37,11 @@ const isCurrentBranchProbe = (args) => args.currentBranch === true && (args._[0]
 */
 const isConfigInit = (args) => args._[0] === "config" && args._[1] === "init" && args.fromBranch !== true && !process.argv.includes("--from-branch");
 /**
+* `config add` edits the local `neon.ts` and never calls the Neon API, so the global auth
+* middleware and the single-project resolver skip it, like {@link isConfigInit}.
+*/
+const isConfigAdd = (args) => args._[0] === "config" && args._[1] === "add";
+/**
 * `neon profile …` manages credentials on disk and never calls the Neon API, so the global
 * auth middleware must skip it — mirroring {@link isConfigInit}.
 *
@@ -350,4 +355,4 @@ const globToRegExp = (pattern) => {
 	return new RegExp(`^${source}$`);
 };
 //#endregion
-export { CONTEXT_FILE, applyContext, contextBranch, currentContextFile, enrichFromContext, ensureDirectoryGitignored, ensureGitignored, gitBranchMap, gitBranchMapping, isApiKeysCommand, isAskCommand, isClaimCommand, isConfigInit, isCurrentBranchProbe, 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, isGitLocalCommand, isInspectDbUrl, isMcpCommand, isMcpOauth, isPluginsCommand, isProfileCommand, isSkillsCommand, isUnfollowedGitHookSync, readContextFile, setContext, setGitBranchMap, setGitBranchMapping, setGitFollow, updateContextFile, walkContextFile };

package/dist/utils/enrichers.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neon",
-  "version": "6.3.0",
+  "version": "6.4.0",
   "description": "CLI tool for Neon, the cloud backend primitives built around Lakebase Postgres",
   "keywords": [
     "neon",
@@ -64,9 +64,9 @@
     "yaml": "^2.9.0",
     "yargs": "17.7.2",
     "yoctocolors": "^2.1.2",
-    "@neon/config": "1.8.2",
     "@neon/config-runtime": "1.7.2",
-    "@neon/sdk": "6.1.2"
+    "@neon/sdk": "6.1.2",
+    "@neon/config": "1.8.2"
   },
   "optionalDependencies": {
     "@napi-rs/keyring": "1.3.0",