neon 6.1.0 → 6.2.1

package/dist/commands/git.js

@@ -0,0 +1,356 @@
+import { t as __exportAll } from "../_chunks/rolldown-runtime-8H4AJuhK.js";
+import { isCi } from "../env.js";
+import { log } from "../log.js";
+import { CONTEXT_FILE, contextBranch, gitBranchMap, gitBranchMapping, isUnfollowedGitHookSync, readContextFile, setGitBranchMap, setGitBranchMapping, setGitFollow } from "../context.js";
+import { writer } from "../writer.js";
+import { neonSafeBranchName } from "../utils/branch_name.js";
+import { currentGitBranch, gitPull, gitRepoRoot, hasUpstream, installPostCheckoutHook, isGitRepo, isManagedHook, localGitBranches, postCheckoutHookPath, readGitContext, removePostCheckoutHook } from "../utils/git.js";
+import { quoteFlagValue } from "./link.js";
+import { handler as handler$1 } from "./checkout.js";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import chalk from "chalk";
+import prompts from "prompts";
+//#region src/commands/git.ts
+var git_exports = /* @__PURE__ */ __exportAll({
+	aliases: () => aliases,
+	builder: () => builder,
+	cleanup: () => cleanup,
+	command: () => "git",
+	describe: () => describe,
+	handler: () => handler,
+	install: () => install,
+	partitionBranchesToPrune: () => partitionBranchesToPrune,
+	status: () => status,
+	sync: () => sync,
+	uninstall: () => uninstall
+});
+const command = "git";
+const describe = "Sync the checked-out Neon branch to your git branch (Preview)";
+const aliases = [];
+const builder = (argv) => argv.usage("$0 git <sub-command> [options]").command("install", "Install a git post-checkout hook that syncs the Neon branch on `git checkout`", (yargs) => yargs.epilogue("Requires a project already linked at the repository root — run `neon link` or `neon checkout <branch>` there first."), (args) => {
+	install(args);
+}).command("uninstall", "Remove the git post-checkout hook installed by `git install`", (yargs) => yargs, (args) => {
+	uninstall(args);
+}).command("sync", "Check out the Neon branch mapped to the current git branch (run by the hook)", (yargs) => yargs.options({
+	"env-pull": {
+		describe: "Pull the branch's Neon env vars into a local .env after sync. On by default.",
+		type: "boolean",
+		default: true
+	},
+	pull: {
+		describe: "Run `git pull --ff-only` before syncing so local files (incl. migration files) match the branch before any checkout.after migration runs. Without the flag, prompts when run manually in a TTY and skips in the hook / CI.",
+		type: "boolean"
+	},
+	quiet: {
+		describe: "Suppress sync's own routine status lines (git pull result, detached HEAD notice). Warnings and the delegated checkout's own output are unaffected. Used by the installed git hook.",
+		type: "boolean",
+		default: false
+	}
+}), (args) => sync(args)).command("status", "Show the git context, hook state, and current git → Neon mapping", (yargs) => yargs, (args) => {
+	status(args);
+}).command("cleanup", "Prune git → Neon mappings whose local git branch is gone; optionally delete the orphaned Neon branches", (yargs) => yargs.options({
+	"prune-neon-branches": {
+		describe: "Also delete the orphaned Neon branches (never the default or a protected branch).",
+		type: "boolean",
+		default: false
+	},
+	yes: {
+		describe: "Skip the confirmation prompt before deleting Neon branches.",
+		type: "boolean",
+		default: false
+	}
+}), (args) => cleanup(args));
+const handler = (args) => args;
+const requireRepoRoot = () => {
+	const cwd = process.cwd();
+	if (!isGitRepo(cwd)) throw new Error("Not inside a git repository. Run `neon git` from a git work tree.");
+	const repoRoot = gitRepoRoot(cwd);
+	if (!repoRoot) throw new Error("Could not resolve the git repository root.");
+	return repoRoot;
+};
+/**
+* `.neon` at exactly the repo root — never walk-up-resolved. The single source of truth for
+* all git-hooks state: `git.follow` and the git → Neon map. A `post-checkout` hook always
+* runs with `cwd` at the repo root, so every function here (`install`, `uninstall`, `sync`,
+* `status`, `cleanup`) reads and writes this exact path, never `props.contextFile`'s
+* walk-up resolution — an ancestor directory's unrelated `.neon` (e.g. a parent monorepo
+* folder) must never be mistaken for this repo's own state.
+*
+* Deliberately never *creates* this file: `install` requires it to already exist (from a
+* prior `neon link` / `neon checkout` run at the repo root), and `sync` skips persisting a
+* mapping when it's absent. Auto-creating a bare `{ git: {...} }` file with no `projectId`
+* would plant a **new**, closer `.neon` that shadows a real project link recorded in an
+* ancestor directory (or a linked subdirectory) for every other command's normal
+* context resolution — silently breaking `checkout` / `deploy` / `status` in that
+* directory. Requiring the link first also keeps this file and the project context file
+* the same file whenever hooks state exists, which is what makes `cleanup`'s project-match
+* check (see below) actually correct.
+*/
+const repoRootContextFile = (repoRoot) => join(repoRoot, CONTEXT_FILE);
+const install = (_props) => {
+	const repoRoot = requireRepoRoot();
+	const gitStateFile = repoRootContextFile(repoRoot);
+	if (!readContextFile(gitStateFile).projectId) {
+		const quoted = quoteFlagValue(gitStateFile);
+		throw new Error(`No project linked at the repository root (${gitStateFile}).\nRun \`neon link --context-file ${quoted}\` (an explicit path, since a plain \`neon link\` walks up and may update a different, ancestor \`.neon\` instead) or \`neon checkout <branch> --context-file ${quoted}\` first, then re-run \`neon git install\`.`);
+	}
+	const result = installPostCheckoutHook(repoRoot);
+	if (result.status === "conflict") throw new Error(`A non-neon \`post-checkout\` hook already exists at ${result.hookPath}.\nRemove or rename it first, then re-run \`neon git install\`.`);
+	setGitFollow(gitStateFile, true);
+	log.info("Git → Neon sync %s. `git checkout <branch>` will now check out the mapped Neon branch.\nHook: %s", result.status === "installed" ? "installed" : "updated", postCheckoutHookPath(repoRoot));
+};
+const uninstall = (_props) => {
+	const repoRoot = requireRepoRoot();
+	const result = removePostCheckoutHook(repoRoot);
+	const gitStateFile = repoRootContextFile(repoRoot);
+	if (existsSync(gitStateFile)) setGitFollow(gitStateFile, false);
+	switch (result) {
+		case "removed":
+			log.info("Removed the neon git post-checkout hook. Git → Neon sync is off.");
+			break;
+		case "foreign":
+			log.warning("Left the existing `post-checkout` hook in place (not managed by neon). Git → Neon sync flag cleared.");
+			break;
+		case "absent": log.info("No neon git hook was installed. Git → Neon sync flag cleared.");
+	}
+};
+/**
+* Check out the Neon branch that corresponds to the current git branch. Invoked by the
+* installed `post-checkout` hook (with `NEON_GIT_HOOK=1`) and runnable by hand. Resolves the
+* Neon branch name via the persisted map (sticky), delegates to `neon checkout` (whose
+* `checkout.before` hook may further map the name and whose `checkout.after` hook runs
+* migrations, etc.), then records the resulting git → Neon mapping so it stays stable.
+*/
+/** `sync`'s own routine status lines (pull result, detached HEAD) — skipped under
+* `--quiet`. Warnings, errors, and the delegated `checkout`'s own output are unaffected. */
+const syncLog = (props, ...args) => {
+	if (props.quiet) return;
+	log.info(...args);
+};
+const sync = async (props) => {
+	if (isUnfollowedGitHookSync({ _: ["git", "sync"] })) {
+		log.debug("Skipping git sync: this repo has not run `neon git install` (git.follow is not set).");
+		return;
+	}
+	const cwd = process.cwd();
+	if (!isGitRepo(cwd)) throw new Error("Not inside a git repository.");
+	const repoRoot = gitRepoRoot(cwd) ?? cwd;
+	const gitStateFile = repoRootContextFile(repoRoot);
+	const context = readContextFile(gitStateFile);
+	const gitBranch = currentGitBranch(cwd);
+	if (!gitBranch) {
+		syncLog(props, "Detached HEAD — no git branch to sync. Skipping.");
+		return;
+	}
+	if (await resolveShouldPull(props, cwd, gitBranch)) {
+		const outcome = gitPull(cwd);
+		switch (outcome.status) {
+			case "pulled":
+				syncLog(props, "%s git pull --ff-only (%s)", chalk.dim("→"), gitBranch);
+				break;
+			case "no-upstream":
+				syncLog(props, "No upstream for %s — skipping git pull.", gitBranch);
+				break;
+			case "failed": log.warning("git pull --ff-only failed (continuing with sync): %s", outcome.detail);
+		}
+	}
+	const inputName = gitBranchMapping(context, gitBranch) ?? neonSafeBranchName(gitBranch);
+	await handler$1({
+		...props,
+		id: inputName,
+		envPull: props.envPull ?? true
+	});
+	const rootProjectId = readContextFile(gitStateFile).projectId;
+	const pinnedContext = readContextFile(props.contextFile);
+	if (!rootProjectId || pinnedContext.projectId !== rootProjectId) log.warning("Not persisting the git → Neon mapping: this checkout targeted project %s, not a project linked at the repo root (%s).", pinnedContext.projectId ?? "(unknown)", rootProjectId ?? "none");
+	else {
+		const resolved = contextBranch(pinnedContext);
+		if (resolved) setGitBranchMapping(gitStateFile, gitBranch, resolved);
+	}
+};
+/**
+* Decide whether `git sync` should `git pull` first. Mirrors the rest of the CLI's
+* auto-vs-interactive philosophy (cf. `checkout` / `link`): an explicit flag always wins;
+* otherwise we only *prompt* in a real manual TTY, and never auto-pull in the post-checkout
+* hook or CI (no network surprises in automation). Skips when there's nothing upstream.
+*/
+const resolveShouldPull = async (props, cwd, gitBranch) => {
+	if (props.pull === true) return true;
+	if (props.pull === false) return false;
+	if (!hasUpstream(cwd)) return false;
+	if (process.env["NEON_GIT_HOOK"] === "1" || isCi() || !process.stdout.isTTY) return false;
+	const { pull } = await prompts({
+		type: "confirm",
+		name: "pull",
+		message: `Pull latest for "${gitBranch}" (git pull --ff-only) before syncing?`,
+		initial: false
+	});
+	return Boolean(pull);
+};
+const GIT_STATUS_FIELDS = [
+	"gitBranch",
+	"hookInstalled",
+	"followOnCheckout",
+	"mappedNeonBranch",
+	"mappings"
+];
+const status = (props) => {
+	const cwd = process.cwd();
+	const git = readGitContext(cwd);
+	if (!git.available) throw new Error("Not inside a git repository.");
+	const repoRoot = git.repoRoot ?? cwd;
+	const hookPath = postCheckoutHookPath(repoRoot);
+	const context = readContextFile(repoRootContextFile(repoRoot));
+	const currentBranch = git.branch;
+	writer(props).end({
+		gitBranch: currentBranch ?? null,
+		hookInstalled: isManagedHook(hookPath),
+		followOnCheckout: context.git?.follow === true,
+		mappedNeonBranch: currentBranch ? gitBranchMapping(context, currentBranch) ?? null : null,
+		mappings: context.git?.map ?? {}
+	}, {
+		fields: GIT_STATUS_FIELDS,
+		renderColumns: {
+			gitBranch: (v) => v.gitBranch ?? "(detached)",
+			mappedNeonBranch: (v) => v.gitBranch === null ? "(detached — sync skips detached HEAD)" : v.mappedNeonBranch ?? "(unmapped — will derive on next sync)",
+			mappings: (v) => Object.entries(v.mappings).map(([gitBranch, neonBranch]) => `${gitBranch} → ${neonBranch}`).join("\n") || "(none)"
+		}
+	});
+};
+/**
+* Split the orphaned Neon branches (those mapped from now-deleted git branches) into the ones
+* safe to delete and the ones to skip. Default and protected branches are **never** deleted.
+* Pure (no I/O) so it's unit-testable.
+*/
+const partitionBranchesToPrune = (branches, orphanNeonNames) => {
+	const toDelete = [];
+	const skipped = [];
+	for (const branch of branches) {
+		if (!orphanNeonNames.has(branch.name)) continue;
+		if (branch.default) skipped.push({
+			name: branch.name,
+			reason: "default branch"
+		});
+		else if (branch.protected) skipped.push({
+			name: branch.name,
+			reason: "protected"
+		});
+		else toDelete.push(branch);
+	}
+	return {
+		toDelete,
+		skipped
+	};
+};
+/**
+* Prune the git → Neon workflow state. By default this only cleans `.neon`: mapping entries
+* whose git branch no longer exists locally are dropped. With `--prune-neon-branches` it also
+* deletes the orphaned Neon branches — never the default branch and never a protected one.
+*/
+const cleanup = async (props) => {
+	const cwd = process.cwd();
+	if (!isGitRepo(cwd)) throw new Error("Not inside a git repository.");
+	const repoRoot = gitRepoRoot(cwd) ?? cwd;
+	const gitStateFile = repoRootContextFile(repoRoot);
+	const context = readContextFile(gitStateFile);
+	const map = gitBranchMap(context);
+	const entries = Object.entries(map);
+	if (entries.length === 0) {
+		log.info("No git → Neon mappings to clean up.");
+		return;
+	}
+	const local = new Set(localGitBranches(cwd));
+	const stale = entries.filter(([gitBranch]) => !local.has(gitBranch));
+	if (stale.length === 0) {
+		log.info("All %d mapping(s) still have a local git branch — nothing to prune.", entries.length);
+		return;
+	}
+	const kept = Object.fromEntries(entries.filter(([gitBranch]) => local.has(gitBranch)));
+	const keptNeonNames = new Set(Object.values(kept));
+	const staleButShared = stale.filter(([, neonBranch]) => keptNeonNames.has(neonBranch));
+	const orphaned = stale.filter(([, neonBranch]) => !keptNeonNames.has(neonBranch));
+	if (!props.pruneNeonBranches) {
+		setGitBranchMap(gitStateFile, kept);
+		log.info("Pruned %d stale mapping(s) from .neon:", stale.length);
+		for (const [gitBranch, neonBranch] of stale) log.info("  %s → %s", gitBranch, neonBranch);
+		if (orphaned.length > 0) log.info("These Neon branch(es) are no longer mapped and were not deleted: %s. Delete them with `neon branches delete <name>`, or run `neon git cleanup --prune-neon-branches` next time before a mapping-only cleanup.", orphaned.map(([, neonBranch]) => neonBranch).join(", "));
+		return;
+	}
+	if (staleButShared.length > 0) {
+		setGitBranchMap(gitStateFile, {
+			...kept,
+			...Object.fromEntries(orphaned)
+		});
+		log.info("Pruned %d stale mapping(s) whose Neon branch is still in use elsewhere:", staleButShared.length);
+		for (const [gitBranch, neonBranch] of staleButShared) log.info("  %s → %s", gitBranch, neonBranch);
+	}
+	if (!props.projectId) throw new Error("Cannot delete Neon branches: no project in context. Run `neon link` first.");
+	if (!context.projectId) throw new Error(`Cannot delete Neon branches: the git → Neon map has no recorded project (the repo-root .neon at ${gitStateFile} has no projectId). Run \`neon link --context-file ${quoteFlagValue(gitStateFile)}\` to establish it, or \`neon git cleanup\` with no --prune-neon-branches to only prune the local mapping.`);
+	if (context.projectId !== props.projectId) throw new Error(`Cannot delete Neon branches: this git → Neon map was recorded against project ${context.projectId}, but the active project is ${props.projectId}. Run \`neon link\` (or drop --project-id) to target ${context.projectId}, or \`neon git cleanup\` with no --prune-neon-branches to only prune the local mapping.`);
+	if (orphaned.length === 0) {
+		log.info("No orphaned Neon branches to delete.");
+		return;
+	}
+	const orphanNeonNames = new Set(orphaned.map(([, neonBranch]) => neonBranch));
+	const branches = (await props.apiClient.listProjectBranches({ projectId: props.projectId })).data.branches;
+	const { toDelete, skipped } = partitionBranchesToPrune(branches, orphanNeonNames);
+	for (const { name, reason } of skipped) log.warning("Keeping Neon branch %s (%s) — never auto-deleted.", name, reason);
+	if (toDelete.length === 0) {
+		log.info("No orphaned Neon branches to delete.");
+		return;
+	}
+	if (!await confirmPrune(props, toDelete)) {
+		log.info("Aborted — no Neon branches were deleted, and no mappings were pruned.");
+		return;
+	}
+	const currentMap = {
+		...kept,
+		...Object.fromEntries(orphaned)
+	};
+	const failed = [];
+	let prunedCount = 0;
+	for (const branch of toDelete) {
+		const branchMappings = orphaned.filter(([, neonBranch]) => neonBranch === branch.name);
+		try {
+			await props.apiClient.deleteProjectBranch(props.projectId, branch.id);
+			log.info("Deleted Neon branch %s (%s).", branch.name, branch.id);
+			prunedCount += branchMappings.length;
+			for (const [gitBranch, neonBranch] of branchMappings) {
+				log.info("  Pruned %s → %s", gitBranch, neonBranch);
+				delete currentMap[gitBranch];
+			}
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			log.error("Failed to delete Neon branch %s: %s", branch.name, message);
+			failed.push({
+				name: branch.name,
+				error: message
+			});
+		}
+		setGitBranchMap(gitStateFile, currentMap);
+	}
+	if (prunedCount > 0) log.info("Pruned %d stale mapping(s) from .neon.", prunedCount);
+	if (failed.length > 0) throw new Error(`Failed to delete ${failed.length} Neon branch(es): ${failed.map((f) => `${f.name} (${f.error})`).join(", ")}. Re-run \`neon git cleanup --prune-neon-branches\` to retry.`);
+};
+/**
+* Confirm deleting the orphaned Neon branches. Deletion is destructive, so an explicit
+* `--yes` wins; otherwise prompt in an interactive terminal, and refuse (with a warning) in
+* CI / non-interactive contexts rather than deleting without consent.
+*/
+const confirmPrune = async (props, toDelete) => {
+	if (props.yes) return true;
+	if (isCi() || !process.stdout.isTTY) {
+		log.warning("Refusing to delete %d Neon branch(es) non-interactively. Re-run with --yes to confirm.", toDelete.length);
+		return false;
+	}
+	const { ok } = await prompts({
+		type: "confirm",
+		name: "ok",
+		message: `Delete ${toDelete.length} orphaned Neon branch(es): ${toDelete.map((branch) => branch.name).join(", ")}?`,
+		initial: false
+	});
+	return Boolean(ok);
+};
+//#endregion
+export { aliases, builder, cleanup, command, describe, handler, install, partitionBranchesToPrune, status, sync, git_exports as t, uninstall };

package/dist/commands/index.js

@@ -22,6 +22,7 @@ import { t as deploy_exports } from "./deploy.js";
 import { t as dev_exports } from "./dev.js";
 import { t as diff_exports } from "./diff.js";
 import { t as functions_exports } from "./functions.js";
+import { t as git_exports } from "./git.js";
 import { t as init_exports } from "./init.js";
 import { t as inspect_exports } from "./inspect.js";
 import { t as ip_allow_exports } from "./ip_allow.js";
@@ -62,6 +63,7 @@ var commands_default = [
 	psql_exports,
 	set_context_exports,
 	checkout_exports,
+	git_exports,
 	link_exports,
 	open_exports,
 	claim_exports,

package/dist/commands/link.js

@@ -21,6 +21,7 @@ var link_exports = /* @__PURE__ */ __exportAll({
 	command: () => command,
 	describe: () => describe,
 	handler: () => handler,
+	quoteFlagValue: () => quoteFlagValue,
 	runLink: () => runLink,
 	shouldOfferConfigInit: () => shouldOfferConfigInit
 });
@@ -887,4 +888,4 @@ const mustString = (value, name) => {
 	return value;
 };
 //#endregion
-export { builder, command, describe, handler, runLink, shouldOfferConfigInit, link_exports as t };
+export { builder, command, describe, handler, quoteFlagValue, runLink, shouldOfferConfigInit, link_exports as t };

package/dist/context.js

@@ -52,6 +52,34 @@ const isClaimCommand = (args) => args._[0] === "claim" || args._[0] === "claimab
 */
 const isApiKeysCommand = (args) => args._[0] === "api-keys" || args._[0] === "api-key";
 const isMcpCommand = (args) => args._[0] === "mcp";
+/**
+* `neon git install/uninstall/status` only touch the local git hooks directory and `.neon`
+* — never the Neon API — so they must work (and never pop a browser login) without
+* credentials, the same reasoning as {@link isProfileCommand}. `sync` and `cleanup` are
+* excluded: both can reach the API (`sync` always delegates to `checkout`; `cleanup` does
+* too with `--prune-neon-branches`).
+*/
+const isGitLocalCommand = (args) => args._[0] === "git" && (args._[1] === "install" || args._[1] === "uninstall" || args._[1] === "status");
+/** The env var the installed `post-checkout` hook sets before invoking `neon git sync`. */
+const GIT_HOOK_ENV_FLAG = "NEON_GIT_HOOK";
+/**
+* True only for a `neon git sync` invocation triggered by the installed `post-checkout`
+* hook, in a repo that has **not** itself run `neon git install` — the case that must never
+* touch the network (auth included). Checked before authentication runs at all, since
+* `core.hooksPath` can point at a directory shared by several repositories: the hook script
+* firing here does not by itself mean *this* repo opted in.
+*
+* The `.neon` read is deliberately **not** the usual walk-up resolution
+* ({@link currentContextFile}): a `post-checkout` hook always runs with `cwd` at the
+* repository's top level, and opt-in must be recorded by *this* repo's own `.neon` — an
+* ancestor directory's `.neon` (found by the walk-up, e.g. a parent monorepo folder that
+* happens to hold one for an unrelated project) must never authorize it.
+*/
+const isUnfollowedGitHookSync = (args, cwd = process.cwd()) => {
+	if (!(args._[0] === "git" && args._[1] === "sync")) return false;
+	if (process.env[GIT_HOOK_ENV_FLAG] !== "1") return false;
+	return readContextFile(resolve(cwd, CONTEXT_FILE)).git?.follow !== true;
+};
 const isSkillsCommand = (args) => args._[0] === "skills" || args._[0] === "skill";
 const isPluginsCommand = (args) => args._[0] === "plugins" || args._[0] === "plugin";
 const isAskCommand = (args) => args._[0] === "ask";
@@ -163,12 +191,73 @@ const updateContextFile = (file, context) => {
 * `.neon` we never touch `.gitignore`, so a user who deliberately un-ignored
 * the file (e.g. to commit shared context) won't have the entry re-added on
 * every subsequent command.
+*
+* The {@link Context.git} block is additionally **preserved** when the caller doesn't
+* provide one, so a plain `link` / `set-context` / `checkout` never wipes the git → Neon
+* mapping a user (or `neon git sync`) built up. Pass an explicit `git` to replace it.
+*
+* That preservation is skipped when `context.projectId` differs from the file's existing
+* `projectId`: the mapping's Neon branch **names** are only meaningful within the project
+* they were recorded against, and carrying them into a different project could point
+* `neon git cleanup --prune-neon-branches` at a same-named branch that was never actually
+* mapped there.
 */
 const applyContext = (file, context) => {
 	const isNewFile = !existsSync(file);
-	updateContextFile(file, context);
+	const existing = isNewFile ? {} : readContextFile(file);
+	const projectChanged = existing.projectId !== void 0 && context.projectId !== existing.projectId;
+	const merged = context.git === void 0 && existing.git !== void 0 && !projectChanged ? {
+		...context,
+		git: existing.git
+	} : context;
+	updateContextFile(file, merged);
 	if (isNewFile) ensureGitignored(file);
 };
+/** Look up the Neon branch a git branch maps to in the persisted `.neon` context. */
+const gitBranchMapping = (context, gitBranch) => context.git?.map?.[gitBranch];
+/** The full git → Neon mapping from the context (a copy; empty when unset). */
+const gitBranchMap = (context) => ({ ...context.git?.map });
+/** Replace the git → Neon mapping in `.neon`, preserving `git.follow` and the rest. */
+const setGitBranchMap = (file, map) => {
+	const context = readContextFile(file);
+	applyContext(file, {
+		...context,
+		git: {
+			...context.git,
+			map
+		}
+	});
+};
+/**
+* Record a git branch -> Neon branch mapping in `.neon`, merging into any existing map and
+* preserving the rest of the context. Passes an explicit `git` so {@link applyContext}
+* replaces (rather than just preserves) the block with the new entry folded in.
+*/
+const setGitBranchMapping = (file, gitBranch, neonBranch) => {
+	const context = readContextFile(file);
+	const git = {
+		...context.git,
+		map: {
+			...context.git?.map,
+			[gitBranch]: neonBranch
+		}
+	};
+	applyContext(file, {
+		...context,
+		git
+	});
+};
+/** Set the `git.follow` flag (whether the post-checkout hook drives `neon git sync`). */
+const setGitFollow = (file, follow) => {
+	const context = readContextFile(file);
+	applyContext(file, {
+		...context,
+		git: {
+			...context.git,
+			follow
+		}
+	});
+};
 /**
 * Low-level writer for callers that already hold the resolved identifiers and
 * just need to record them — e.g. `init` or `projects create`, which create a
@@ -231,7 +320,7 @@ const ensureGitignoreEntry = (path, entry) => {
 };
 const basenameOf = (file) => {
 	const parts = file.split(/[\\/]/);
-	return parts[parts.length - 1] || CONTEXT_FILE;
+	return parts[parts.length - 1] || ".neon";
 };
 const hasGitignoreEntry = (content, entry) => {
 	return content.split(/\r?\n/).some((line) => gitignoreCovers(line.trim(), entry));
@@ -261,4 +350,4 @@ const globToRegExp = (pattern) => {
 	return new RegExp(`^${source}$`);
 };
 //#endregion
-export { applyContext, contextBranch, currentContextFile, enrichFromContext, ensureDirectoryGitignored, ensureGitignored, isApiKeysCommand, isAskCommand, isClaimCommand, isConfigInit, isCurrentBranchProbe, isInspectDbUrl, isMcpCommand, isMcpOauth, isPluginsCommand, isProfileCommand, isSkillsCommand, readContextFile, setContext, updateContextFile, walkContextFile };
+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 };

package/dist/dev/env.js

@@ -1,2 +1,2 @@
-import { a as resolveDevEnv, i as dropClaimableUnsupported, n as MissingBranchContextError, o as resolveNeonEnvVars, r as ServiceNotOnBranchError, t as DevEnvMismatchError } from "../_chunks/env-DRpFX-_d.js";
+import { a as resolveDevEnv, i as dropClaimableUnsupported, n as MissingBranchContextError, o as resolveNeonEnvVars, r as ServiceNotOnBranchError, t as DevEnvMismatchError } from "../_chunks/env-CtOH9xsl.js";
 export { DevEnvMismatchError, MissingBranchContextError, ServiceNotOnBranchError, dropClaimableUnsupported, resolveDevEnv, resolveNeonEnvVars };

package/dist/env_services.js

@@ -1,2 +1,121 @@
-import { a as envKeysForSelection, c as ownedEnvServiceKeys, d as servicesForEnvKeys, i as ENV_PULL_SERVICES, l as parseEnvPullKeys, n as ENV_PULL_KEYS, o as envPullFlagValue, r as ENV_PULL_KEY_HELP, s as envServiceKeys, t as BRANCH_ENV_KEY, u as serviceForEnvKey } from "./_chunks/env_services-DlXECBPi.js";
+import { NEON_SERVICES } from "./neon_services.js";
+import { f as parseFunctionBaseUrlKey, t as NEON_ENV_VAR_KEYS, u as isFunctionBaseUrlKey } from "./_chunks/env-N19A7qND.js";
+//#region src/env_services.ts
+const ENV_PULL_SERVICES = NEON_SERVICES;
+const ENV_PULL_KEYS = [
+	...Object.values(NEON_ENV_VAR_KEYS.postgres),
+	NEON_ENV_VAR_KEYS.branch.name,
+	...Object.values(NEON_ENV_VAR_KEYS.auth),
+	...Object.values(NEON_ENV_VAR_KEYS.dataApi),
+	...Object.values(NEON_ENV_VAR_KEYS.storage),
+	...Object.values(NEON_ENV_VAR_KEYS.aiGateway)
+];
+const ENV_PULL_KEY_HELP = `${ENV_PULL_KEYS.join(", ")}, or NEON_FUNCTION_<SLUG>_BASE_URL`;
+/** The OS-level env vars each service contributes to a pulled `.env`. */
+const SERVICE_ENV_KEYS = {
+	postgres: Object.values(NEON_ENV_VAR_KEYS.postgres),
+	auth: Object.values(NEON_ENV_VAR_KEYS.auth),
+	"data-api": Object.values(NEON_ENV_VAR_KEYS.dataApi),
+	"object-storage": Object.values(NEON_ENV_VAR_KEYS.storage),
+	"ai-gateway": Object.values(NEON_ENV_VAR_KEYS.aiGateway),
+	functions: []
+};
+/**
+* The subset of {@link SERVICE_ENV_KEYS} a pull *owns*, and so may prune from the target file
+* when the branch no longer has it. Object storage is deliberately absent: it is emitted under
+* the third-party `AWS_*` names, which collide with credentials a user may set by hand, so
+* `env pull` only ever writes them. Function URL keys cannot live here because slugs are
+* discovered at runtime.
+*/
+const SERVICE_OWNED_ENV_KEYS = {
+	...SERVICE_ENV_KEYS,
+	"object-storage": [],
+	functions: []
+};
+/**
+* Branch identity. Not a service — every branch has a name — so a scoped pull refreshes it
+* alongside whatever services were selected.
+*/
+const BRANCH_ENV_KEY = NEON_ENV_VAR_KEYS.branch.name;
+const ENV_KEY_SERVICE = {
+	DATABASE_URL: "postgres",
+	DATABASE_URL_UNPOOLED: "postgres",
+	NEON_BRANCH: null,
+	NEON_AUTH_BASE_URL: "auth",
+	NEON_AUTH_JWKS_URL: "auth",
+	NEON_DATA_API_URL: "data-api",
+	AWS_ACCESS_KEY_ID: "object-storage",
+	AWS_SECRET_ACCESS_KEY: "object-storage",
+	AWS_ENDPOINT_URL_S3: "object-storage",
+	AWS_REGION: "object-storage",
+	NEON_AI_GATEWAY_TOKEN: "ai-gateway",
+	NEON_AI_GATEWAY_BASE_URL: "ai-gateway"
+};
+const serviceForEnvKey = (key) => isFunctionBaseUrlKey(key) ? "functions" : ENV_KEY_SERVICE[key];
+/** Services that must be resolved to produce the selected env keys. */
+const servicesForEnvKeys = (keys) => ENV_PULL_SERVICES.filter((service) => keys.some((key) => serviceForEnvKey(key) === service));
+/** Every env var the selected services contribute, plus branch identity. */
+const envServiceKeys = (services) => {
+	const keys = /* @__PURE__ */ new Set([BRANCH_ENV_KEY]);
+	for (const service of services) for (const key of SERVICE_ENV_KEYS[service]) keys.add(key);
+	return keys;
+};
+/**
+* The env vars a pull scoped to `services` may prune. Narrower than the unscoped set on
+* purpose: `env pull -s ai-gateway` says nothing about `DATABASE_URL`, so it must leave it
+* alone rather than treat its absence from this pull as "the branch no longer has it".
+* Function URL keys cannot live here because slugs are discovered at runtime.
+*/
+const ownedEnvServiceKeys = (services) => services.flatMap((service) => SERVICE_OWNED_ENV_KEYS[service]);
+const envKeysForSelection = (services, envKeys) => {
+	const selected = services.length > 0 ? envServiceKeys(services) : /* @__PURE__ */ new Set();
+	for (const key of envKeys) selected.add(key);
+	if (selected.has(NEON_ENV_VAR_KEYS.storage.accessKeyId) !== selected.has(NEON_ENV_VAR_KEYS.storage.secretAccessKey)) throw new Error("AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY must be selected together: they are two halves of one newly issued object-storage credential. Add the missing key to --env, or use --service object-storage.");
+	const staticKeys = ENV_PULL_KEYS.filter((key) => selected.has(key));
+	const functionKeys = [...selected].filter(isFunctionBaseUrlKey).sort((left, right) => left.localeCompare(right));
+	return [...staticKeys, ...functionKeys];
+};
+/** Parse repeated or comma-separated `--env` values into canonical env-key order. */
+const parseEnvPullKeys = (raw, flag) => {
+	const names = raw.flatMap((value) => value.split(",")).map((name) => name.trim()).filter((name) => name !== "");
+	const supported = `Supported values: ${ENV_PULL_KEY_HELP}.`;
+	if (names.length === 0) throw new Error(`${flag} needs at least one env variable. ${supported}`);
+	const unknown = names.filter((name) => !ENV_PULL_KEYS.some((key) => key === name) && !isFunctionBaseUrlKey(name));
+	if (unknown.length > 0) {
+		const displayNames = unknown.map(redactUnknownEnvValue);
+		const suggestions = [...new Set(unknown.map(suggestEnvPullKey).filter((key) => key !== null))];
+		const suggestion = suggestions.length > 0 ? ` Did you mean ${suggestions.join(" or ")}?` : "";
+		throw new Error(`Unknown env variable${unknown.length === 1 ? "" : "s"} ${displayNames.join(", ")}.${suggestion} ${supported}`);
+	}
+	const staticKeys = ENV_PULL_KEYS.filter((key) => names.includes(key));
+	const functionKeys = [...new Set(names.filter(isFunctionBaseUrlKey))].sort((left, right) => left.localeCompare(right));
+	return [...staticKeys, ...functionKeys];
+};
+const isKnownEnvPullKey = (key) => ENV_PULL_KEYS.some((supportedKey) => supportedKey === key) || isFunctionBaseUrlKey(key);
+const redactUnknownEnvValue = (value) => {
+	const separator = value.indexOf("=");
+	if (separator !== -1) {
+		const key = value.slice(0, separator);
+		return isKnownEnvPullKey(key) ? `${key}=<redacted>` : "<redacted invalid value>";
+	}
+	return "<redacted invalid value>";
+};
+const suggestEnvPullKey = (value) => {
+	if (value.includes("=")) return null;
+	if (parseFunctionBaseUrlKey(value) !== null) return null;
+	const closest = ENV_PULL_KEYS.map((key) => [key, editDistance(value, key)]).sort((a, b) => a[1] - b[1])[0];
+	return closest && closest[1] <= 2 ? closest[0] : null;
+};
+const editDistance = (left, right) => {
+	let previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+	for (let leftIndex = 1; leftIndex <= left.length; leftIndex += 1) {
+		const current = [leftIndex];
+		for (let rightIndex = 1; rightIndex <= right.length; rightIndex += 1) current[rightIndex] = Math.min((previous[rightIndex] ?? 0) + 1, (current[rightIndex - 1] ?? 0) + 1, (previous[rightIndex - 1] ?? 0) + (left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1));
+		previous = current;
+	}
+	return previous[right.length] ?? right.length;
+};
+/** Narrow yargs' array option value without accepting any other runtime shape. */
+const envPullFlagValue = (value) => Array.isArray(value) ? value.map(String) : void 0;
+//#endregion
 export { BRANCH_ENV_KEY, ENV_PULL_KEYS, ENV_PULL_KEY_HELP, ENV_PULL_SERVICES, envKeysForSelection, envPullFlagValue, envServiceKeys, ownedEnvServiceKeys, parseEnvPullKeys, serviceForEnvKey, servicesForEnvKeys };

package/dist/utils/branch_name.js

@@ -0,0 +1,29 @@
+//#region src/utils/branch_name.ts
+const MAX_LENGTH = 256;
+const FALLBACK_NAME = "branch";
+/** Reduce one path segment to `[a-z0-9-]`, collapsing other runs to `-` and trimming `-`. */
+const sanitizeSegment = (segment) => segment.replace(/[^a-z0-9]+/gi, "-").replace(/^-+/, "").replace(/-+$/, "");
+/**
+* Convert a git branch name into a valid, stable Neon branch name — lowercased, each
+* `/`-separated segment reduced to `[a-z0-9-]` (runs of other characters collapsed to a
+* single `-`, leading/trailing `-` trimmed), `/` preserved as a segment separator so a
+* hierarchical branch like `feature/billing-ui` round-trips unchanged, empty results fall
+* back to `"branch"`, and the result is clamped to 256 characters (Neon's branch-name
+* limit). This is the computation behind `GitContext.neonSafeBranchName` (from
+* `@neon/config`) — call it directly only where you don't already have a `GitContext`
+* (e.g. `neon git sync` deriving the default Neon branch name for the current git branch).
+*
+* @example neonSafeBranchName("feature/PROJ-123 Add Billing") // "feature/proj-123-add-billing"
+* @example neonSafeBranchName("Hotfix!!") // "hotfix"
+*/
+const neonSafeBranchName = (gitBranch) => {
+	const name = gitBranch.toLowerCase().split("/").map(sanitizeSegment).filter((segment) => segment.length > 0).join("/");
+	if (name.length === 0) return FALLBACK_NAME;
+	if (name.length > MAX_LENGTH) {
+		const clamped = name.slice(0, MAX_LENGTH).replace(/[-/]+$/, "");
+		return clamped.length === 0 ? FALLBACK_NAME : clamped;
+	}
+	return name;
+};
+//#endregion
+export { neonSafeBranchName };