neon 6.0.0 → 6.2.0

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

@@ -6,6 +6,9 @@ import { t as env_exports } from "./env.js";
 import { t as config_exports } from "./config.js";
 import { t as projects_exports } from "./projects.js";
 import { t as link_exports } from "./link.js";
+import { t as mcp_exports } from "./mcp.js";
+import { t as plugins_exports } from "./plugins.js";
+import { t as skills_exports } from "./skills.js";
 import { t as bootstrap_exports } from "./bootstrap.js";
 import { t as branches_exports } from "./branches.js";
 import { t as bucket_exports } from "./bucket.js";
@@ -19,21 +22,19 @@ 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";
 import { t as logs_exports } from "./logs.js";
-import { t as mcp_exports } from "./mcp.js";
 import { t as neon_auth_exports } from "./neon_auth.js";
 import { t as open_exports } from "./open.js";
 import { t as operations_exports } from "./operations.js";
 import { t as orgs_exports } from "./orgs.js";
-import { t as plugins_exports } from "./plugins.js";
 import { t as profile_exports } from "./profile.js";
 import { t as psql_exports } from "./psql.js";
 import { t as roles_exports } from "./roles.js";
 import { t as set_context_exports } from "./set_context.js";
-import { t as skills_exports } from "./skills.js";
 import { t as snapshots_exports } from "./snapshots.js";
 import { t as status_exports } from "./status.js";
 import { t as triggers_exports } from "./triggers.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/init.js

@@ -3,7 +3,6 @@ import { getCliName } from "../utils/cli_name.js";
 import { helpCsv, helpEpilogue } from "../utils/help_text.js";
 import { servicesOption } from "../neon_services.js";
 import { CONFIG_INIT_NONE_MEANS, CONFIG_INIT_SERVICES } from "../config_template.js";
-import { initChildEnv } from "../init/child.js";
 import { coerceAgentFlag } from "../utils/agent_flag.js";
 import { initPluginAgents, initSkillsMcpAgents } from "../init/plan.js";
 import { listSkillIds } from "../skills/catalog.js";
@@ -13,8 +12,7 @@ var init_exports = /* @__PURE__ */ __exportAll({
 	builder: () => builder,
 	command: () => command,
 	describe: () => describe,
-	handler: () => handler,
-	initChildEnv: () => initChildEnv
+	handler: () => handler
 });
 const command = "init";
 const describe = "Set up coding agents and this directory for Neon. -y is Recommended. -y with Custom flags applies those answers without prompts.";
@@ -108,4 +106,4 @@ const handler = async (props) => {
 	await runInit(props);
 };
 //#endregion
-export { builder, command, describe, handler, initChildEnv, init_exports as t };
+export { builder, command, describe, handler, init_exports as t };

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/commands/mcp.js

@@ -8,15 +8,18 @@ import { writer } from "../writer.js";
 import { noPassthrough, single } from "../utils/flags.js";
 import { NEON_MCP_CATEGORIES, NEON_MCP_URL, existingNeonApiKey, installNeonMcpServer, neonMcpUrl, parseMcpCategories, trackedProjectMcpConfig } from "../mcp/install.js";
 import { mcpInstallableAgents, resolveInstallTargets } from "../mcp/targets.js";
-import { canPickAgentsInteractively } from "../utils/agent_picker.js";
 import { mintMcpApiKey, mintedKeyRevokeCommand, withdrawMintedKey } from "../mcp/mint.js";
+import { canPickAgentsInteractively } from "../utils/agent_picker.js";
 import { resolveMcpPlan } from "../mcp/plan.js";
 //#region src/commands/mcp.ts
 var mcp_exports = /* @__PURE__ */ __exportAll({
 	builder: () => builder,
 	command: () => "mcp",
 	describe: () => describe,
-	handler: () => handler
+	handler: () => handler,
+	mcpInstallError: () => mcpInstallError,
+	reportMcpInstall: () => reportMcpInstall,
+	setupNeonMcp: () => setupNeonMcp
 });
 const command = "mcp";
 const describe = "Install the Neon MCP server into coding agents";
@@ -87,20 +90,29 @@ const builder = (argv) => argv.usage("$0 mcp [options]").options({
 		}
 	}
 }).example("$0 mcp", "Interactive: config location, agents, then auth").example("$0 mcp -y", "Global config, installed apps else the host CLI agent, reuse or mint an API key").example("$0 mcp --oauth", "Install with OAuth; the agent signs in on first use").example("$0 mcp --agent cursor --agent claude-code", "Install into specific agents").example("$0 mcp --project", "Write project-level config").example("$0 mcp --read-only", "Hide write tools via ?readonly=true").example("$0 mcp --project-id <id>", "Pin tools to one project via ?projectId=").example("$0 mcp --category querying --category schema", "Limit tools to those categories").epilogue(helpEpilogue(`Installs ${NEON_MCP_URL}`, helpCsv("Supported agents at global scope", mcpGlobalAgents), helpCsv("--project does not support", mcpProjectDroppedAgents), helpCsv("Supported categories", NEON_MCP_CATEGORIES), "neon mcp -y:", "  global config", "  globally installed apps, else the host CLI agent", "  reuse an existing Neon MCP API key, else mint an account-wide key", "  write tools on, all categories", "  no project pin (including from .neon)")).strict().check(noPassthrough("mcp"));
-const handler = async (props) => {
-	const cwd = process.cwd();
-	const interactive = canPickAgentsInteractively() && props.yes !== true;
-	const linkedProjectId = readContextFile(props.contextFile).projectId;
+/**
+* Resolves auth, mints or reuses an API key, and writes the Neon MCP server into every
+* resolved agent. No CLI-only concerns here (no `writer` table, no
+* `recordCommandSuccessExtras`): a caller that only wants the outcome — `neon init` /
+* `neon bootstrap` — gets it without rendering a table.
+*
+* Throws directly when zero agents succeed, since that path never reaches a results table
+* worth showing (same as the CLI handler always did).
+*/
+const setupNeonMcp = async (options) => {
+	const cwd = options.cwd ?? process.cwd();
+	const interactive = canPickAgentsInteractively() && options.yes !== true;
+	const linkedProjectId = readContextFile(options.contextFile).projectId;
 	const plan = await resolveMcpPlan({
-		project: props.project === true,
-		oauth: props.oauth === true,
-		agents: props.agent ?? [],
-		yes: props.yes === true,
+		project: options.project === true,
+		oauth: options.oauth === true,
+		agents: options.agent ?? [],
+		yes: options.yes === true,
 		cwd,
 		interactive,
-		readOnly: props.readOnly === true,
-		projectId: props.projectId,
-		categories: props.category ?? [],
+		readOnly: options.readOnly === true,
+		projectId: options.projectId,
+		categories: options.category ?? [],
 		linkedProjectId
 	});
 	const { install, skipped } = resolveInstallTargets({
@@ -125,8 +137,8 @@ const handler = async (props) => {
 		cwd
 	}) : void 0;
 	if (plan.auth === "api-key" && !existing) {
-		if (!props.apiClient || !props.apiKey) throw new Error(`Authentication required. Run \`${getCliName()} auth\`, pass --api-key or use --oauth to install without a Neon credential.`);
-		if (!canPickAgentsInteractively() && props.yes !== true && (props.agent ?? []).length === 0) throw new Error("No interactive terminal. Pass -y to mint into every detected agent, --agent <name> to name them or --oauth to install without minting.");
+		if (!options.apiClient || !options.apiKey) throw new Error(`Authentication required. Run \`${getCliName()} auth\`, pass --api-key or use --oauth to install without a Neon credential.`);
+		if (!canPickAgentsInteractively() && options.yes !== true && (options.agent ?? []).length === 0) throw new Error("No interactive terminal. Pass -y to mint into every detected agent, --agent <name> to name them or --oauth to install without minting.");
 	}
 	let auth;
 	let minted;
@@ -140,7 +152,7 @@ const handler = async (props) => {
 		if (plan.urlProjectId) log.warning("That key keeps its existing scope. Remove the Neon MCP entry to mint a project-scoped key, or pass --oauth to pin tools without a key.");
 	} else {
 		minted = await mintMcpApiKey({
-			apiClient: props.apiClient,
+			apiClient: options.apiClient,
 			projectId: plan.urlProjectId
 		});
 		auth = {
@@ -183,15 +195,28 @@ const handler = async (props) => {
 		error: row.error
 	});
 	if (successes === 0) {
-		if (minted && props.apiClient) {
-			const withdrawn = await withdrawMintedKey(props.apiClient, minted);
+		if (minted && options.apiClient) {
+			const withdrawn = await withdrawMintedKey(options.apiClient, minted);
 			throw new Error(withdrawn ? "Failed to write Neon MCP config to any agent. The minted API key has been revoked." : `Failed to write Neon MCP config to any agent. The minted API key could NOT be revoked. Remove it with \`${mintedKeyRevokeCommand(minted)}\`.`);
 		}
 		throw new Error("Failed to write Neon MCP config to any agent.");
 	}
-	log.info("URL: %s", url);
+	return {
+		scope: plan.scope,
+		rows,
+		failedAgents,
+		url,
+		auth: auth.kind,
+		...minted ? { minted } : {}
+	};
+};
+/** The exact error `neon mcp` throws when some (not all) agents failed, or `undefined` on full success. */
+const mcpInstallError = (outcome) => outcome.failedAgents.length > 0 ? /* @__PURE__ */ new Error(`Failed to write Neon MCP config for: ${outcome.failedAgents.join(", ")}.`) : void 0;
+/** Writes the results table plus the URL/minted-key/OAuth notices. Shared by `neon mcp` and any in-process caller that wants the same human output. */
+const reportMcpInstall = (props, outcome) => {
+	log.info("URL: %s", outcome.url);
 	const out = writer(props);
-	out.write(rows, {
+	out.write(outcome.rows, {
 		fields: [
 			"agent",
 			"status",
@@ -200,10 +225,27 @@ const handler = async (props) => {
 		title: "MCP"
 	});
 	out.end();
-	if (minted) log.info("Minted API key %s (id %d, %s). Revoke with: %s", minted.name, minted.id, minted.projectId ? "project" : "account", mintedKeyRevokeCommand(minted));
-	if (plan.auth === "oauth") log.info("The agent will prompt for Neon sign-in on first use.");
-	if (failedAgents.length > 0) throw new Error(`Failed to write Neon MCP config for: ${failedAgents.join(", ")}.`);
-	recordCommandSuccessExtras({ scope: plan.scope });
+	if (outcome.minted) log.info("Minted API key %s (id %d, %s). Revoke with: %s", outcome.minted.name, outcome.minted.id, outcome.minted.projectId ? "project" : "account", mintedKeyRevokeCommand(outcome.minted));
+	if (outcome.auth === "oauth") log.info("The agent will prompt for Neon sign-in on first use.");
+};
+const handler = async (props) => {
+	const outcome = await setupNeonMcp({
+		apiClient: props.apiClient,
+		apiKey: props.apiKey,
+		contextFile: props.contextFile,
+		cwd: props.cwd,
+		yes: props.yes,
+		oauth: props.oauth,
+		project: props.project,
+		agent: props.agent,
+		readOnly: props.readOnly,
+		projectId: props.projectId,
+		category: props.category
+	});
+	reportMcpInstall(props, outcome);
+	const error = mcpInstallError(outcome);
+	if (error) throw error;
+	recordCommandSuccessExtras({ scope: outcome.scope });
 };
 //#endregion
-export { builder, command, describe, handler, mcp_exports as t };
+export { builder, command, describe, handler, mcpInstallError, reportMcpInstall, setupNeonMcp, mcp_exports as t };