neon 4.6.0 → 4.8.0

package/dist/commands/link.js

@@ -5,8 +5,9 @@ import { isNeonApiError, messageFromBody } from "../api.js";
 import { applyContext, contextBranch, readContextFile, setContext, updateContextFile } from "../context.js";
 import { getCliName } from "../utils/cli_name.js";
 import { createBranch, pickBranchInteractively } from "../utils/branch_picker.js";
-import { autoPullEnvAfterPin, renderAgentPullNote } from "./env.js";
+import { autoPullEnvAfterPin } from "./env.js";
 import { hasNeonConfigFile, initCmd } from "./config.js";
+import { helpEpilogue } from "../utils/help_text.js";
 import { REGIONS } from "./projects.js";
 import prompts from "prompts";
 //#region src/commands/link.ts
@@ -18,6 +19,19 @@ var link_exports = /* @__PURE__ */ __exportAll({
 });
 const PROJECTS_LIST_LIMIT = 100;
 const CREATE_NEW_SENTINEL = "__create_new__";
+const canPromptInteractively = () => !isCi() && Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
+const nonInteractiveLinkCommands = () => {
+	const cli = getCliName();
+	return [
+		`${cli} orgs list --output json`,
+		`${cli} projects list --org-id <org-id> --output json`,
+		`${cli} link --project-id <project-id> [--branch <name> | -y]`,
+		`${cli} link --org-id <org-id> --project-name <name> --region-id aws-us-east-2`
+	];
+};
+const nonInteractiveLinkHelp = () => nonInteractiveLinkCommands().map((command) => `  ${command}`).join("\n");
+const orgScopedKeyHint = "Organization-scoped API keys cannot list orgs; pass --org-id.";
+const removedAgent = () => `\`${getCliName()} link --agent\` was removed.\nUse:\n${nonInteractiveLinkHelp()}\n${orgScopedKeyHint}`;
 const command = "link";
 const describe = "Link the current directory to a Neon project";
 const builder = (argv) => argv.usage("$0 link [options]").options({
@@ -39,7 +53,7 @@ const builder = (argv) => argv.usage("$0 link [options]").options({
 	},
 	branch: {
 		alias: "branch-id",
-		describe: `Branch name or ID to pin in the context (resolved to its ID before writing). Without it, link only resolves the org and project — pin a branch with \`${getCliName()} checkout <branch>\` (link never guesses a default).`,
+		describe: "Branch name or ID to pin in the context (resolved to its name before writing).",
 		type: "string"
 	},
 	params: {
@@ -47,13 +61,12 @@ const builder = (argv) => argv.usage("$0 link [options]").options({
 		type: "string"
 	},
 	agent: {
-		describe: "Emit a JSON state-machine response designed for AI agents instead of prompting. The output is a single JSON object with a discriminated `status` field describing the next step.",
-		type: "boolean",
-		default: false
+		hidden: true,
+		type: "boolean"
 	},
 	yes: {
 		alias: "y",
-		describe: "Skip the \"already linked\" confirmation in interactive mode and re-link anyway.",
+		describe: "Skip the \"already linked\" confirmation, and pin the project's default branch when linking a project that has more than one.",
 		type: "boolean",
 		default: false
 	},
@@ -73,12 +86,16 @@ const builder = (argv) => argv.usage("$0 link [options]").options({
 		default: true
 	}
 }).example([
-	["$0 link --project-id polished-snowflake-12345678", `Link an existing project (org is inferred); pin a branch later with '${getCliName()} checkout'`],
+	["$0 link --project-id polished-snowflake-12345678", "Link an existing project (org is inferred). Pins the only branch; several prompt in a TTY"],
+	["$0 link --project-id polished-snowflake-12345678 -y", "Same, pinning the project's default branch when several exist"],
 	["$0 link --org-id org-… --project-name my-app --region-id aws-us-east-2", "Create a new project and link it"],
 	["$0 link --branch-id br-…", "Pin a branch in the already-linked project"],
 	["$0 link --no-checks --org-id org-… --project-id polished-snowflake-12345678", "Write the context offline (no API calls, no verification)"],
 	["$0 link --clear", "Forget the current org/project/branch context"]
-]);
+]).epilogue(helpEpilogue("Non-interactive (CI, scripts, agents):", ...nonInteractiveLinkCommands().map((command) => `  ${command}`), orgScopedKeyHint)).check((argv) => {
+	if (argv.agent === true) throw new Error(removedAgent());
+	return true;
+});
 const handler = async (props) => {
 	if (props.clear) {
 		clearContext(props.contextFile);
@@ -88,10 +105,6 @@ const handler = async (props) => {
 		runWithoutChecks(props);
 		return;
 	}
-	if (props.agent) {
-		await runAgentSafely(props);
-		return;
-	}
 	const inputs = parseInputs(props);
 	validateInputs(inputs);
 	const existing = readContextFile(props.contextFile);
@@ -99,14 +112,13 @@ const handler = async (props) => {
 		await runNonInteractive(props, inputs, existing);
 		return;
 	}
-	if (isCi()) {
+	if (!canPromptInteractively()) {
 		log.error([
-			"Missing inputs and CI environment detected (no TTY for prompts).",
+			"Missing inputs and no interactive terminal for prompts.",
 			"",
-			"Use one of:",
-			`  ${getCliName()} link --agent                                                    (JSON state machine for agents)`,
-			`  ${getCliName()} link --project-id <project>                                     (link to an existing project; org is inferred)`,
-			`  ${getCliName()} link --org-id <org> --project-name <name> --region-id <region>  (create a new project and link)`
+			"Use:",
+			nonInteractiveLinkHelp(),
+			orgScopedKeyHint
 		].join("\n"));
 		process.exit(1);
 		return;
@@ -155,16 +167,8 @@ const validateInputs = (inputs) => {
 	if (inputs.projectName && inputs.branch) throw new Error(`Conflicting inputs: --branch pins a branch of an existing project, but --project-name creates a new one. Create the project first, then \`${getCliName()} checkout <branch>\`.`);
 };
 /**
-* Whether the inputs (combined with the existing `.neon`) fully determine what
-* to write without prompting the user. Everything else falls back to the
-* interactive picker (TTY) or the CI guard.
-*
-* - `--project-id` is always enough: the org is inferred from the project and
-*   the branch is left to an explicit `checkout` (never auto-defaulted).
-* - `--org-id --project-name --region-id` fully describes a project to create.
-* - `--branch-id` needs a project, which it takes from the existing `.neon`.
-* - `--org-id` on its own just records the default org (merged into any
-*   existing context).
+* Branch selection may still prompt after org and project resolve without the
+* org/project wizard.
 */
 const canResolveNonInteractively = (inputs, existing) => {
 	if (inputs.projectId) return true;
@@ -195,20 +199,6 @@ const runWithoutChecks = (props) => {
 		projectId: inputs.projectId,
 		branch: inputs.branch
 	});
-	if (props.agent) {
-		emitAgent({
-			status: "linked",
-			context_file: props.contextFile,
-			context: {
-				orgId: inputs.orgId,
-				projectId: inputs.projectId,
-				branch: inputs.branch
-			},
-			project: { id: inputs.projectId },
-			message: `Wrote ${props.contextFile} without checks (org ${inputs.orgId}, project ${inputs.projectId}${inputs.branch ? `, branch ${inputs.branch}` : ""}). No verification or env pull was performed.`
-		});
-		return;
-	}
 	printSummary(props, {
 		contextFile: props.contextFile,
 		orgId: inputs.orgId,
@@ -218,25 +208,14 @@ const runWithoutChecks = (props) => {
 		noChecks: true
 	});
 };
-/**
-* A bad user-supplied identifier (project/org/branch that doesn't exist or
-* isn't accessible). Carries an `agentCode` so `--agent` mode can report a
-* precise `status: error` code instead of a generic INTERNAL_ERROR, while the
-* human path just prints the clear `message`.
-*/
 var LinkInputError = class extends Error {
-	constructor(message, agentCode) {
+	constructor(message) {
 		super(message);
 		this.name = "LinkInputError";
-		this.agentCode = agentCode;
 	}
 };
 const httpStatus = (err) => isNeonApiError(err) ? err.status : void 0;
-/**
-* Fetch a project, turning the common failure modes into clear, actionable
-* errors. 401 is rethrown so the global handler can refresh credentials;
-* everything else surfaces as a `LinkInputError` the user (or agent) can act on.
-*/
+/** 401 must reach the global handler so it can refresh credentials. */
 const fetchProjectOrThrow = async (props, projectId) => {
 	try {
 		const { data } = await props.apiClient.getProject(projectId);
@@ -244,8 +223,8 @@ const fetchProjectOrThrow = async (props, projectId) => {
 	} catch (err) {
 		const status = httpStatus(err);
 		if (status === 401) throw err;
-		if (status === 403) throw new LinkInputError(`You don't have access to project '${projectId}'. Check that your API key's account or organization can see it.`, "NO_ACCESS");
-		if (status === 404) throw new LinkInputError(`Project '${projectId}' not found. Double-check the project ID — or that your API key has access to it.`, "NOT_FOUND");
+		if (status === 403) throw new LinkInputError(`You don't have access to project '${projectId}'. Check that your API key's account or organization can see it.`);
+		if (status === 404) throw new LinkInputError(`Project '${projectId}' not found. Double-check the project ID — or that your API key has access to it.`);
 		throw err;
 	}
 };
@@ -263,7 +242,7 @@ const verifyOrgAccess = async (props, orgId) => {
 	} catch (err) {
 		const status = httpStatus(err);
 		if (status === 401) throw err;
-		if (status === 403 || status === 404) throw new LinkInputError(`Organization '${orgId}' not found, or your API key doesn't have access to it. Find your org ID in the Neon Console under Settings.`, status === 403 ? "NO_ACCESS" : "NOT_FOUND");
+		if (status === 403 || status === 404) throw new LinkInputError(`Organization '${orgId}' not found, or your API key doesn't have access to it. Find your org ID in the Neon Console under Settings.`);
 		throw err;
 	}
 };
@@ -278,7 +257,7 @@ const resolveBranchRef = async (props, projectId, branchRef) => {
 	const { data } = await props.apiClient.listProjectBranches({ projectId });
 	const match = data.branches.find((b) => b.id === branchRef) ?? data.branches.find((b) => b.name === branchRef);
 	if (match) return match;
-	throw new LinkInputError(`Branch '${branchRef}' not found in project '${projectId}'. Available branches: ${data.branches.length > 0 ? data.branches.map((b) => `${b.id}${b.name ? ` (${b.name})` : ""}`).join(", ") : "(none)"}. Pin one with \`${getCliName()} checkout <branch>\`.`, "NOT_FOUND");
+	throw new LinkInputError(`Branch '${branchRef}' not found in project '${projectId}'. Available branches: ${data.branches.length > 0 ? data.branches.map((b) => `${b.id}${b.name ? ` (${b.name})` : ""}`).join(", ") : "(none)"}. Pin one with \`${getCliName()} checkout <branch>\`.`);
 };
 /**
 * The value to persist for a branch: prefer its human-readable **name** (nicer
@@ -301,7 +280,7 @@ const branchPersistValue = (branch) => branch.name ?? branch.id;
 const resolveOrgForProject = async (props, inputs, existing, projectId) => {
 	const projectOrg = (await fetchProjectOrThrow(props, projectId)).org_id ?? void 0;
 	if (inputs.orgId) {
-		if (projectOrg && projectOrg !== inputs.orgId) throw new LinkInputError(`Project '${projectId}' belongs to organization '${projectOrg}', not '${inputs.orgId}'. Omit --org-id to use the project's own org, or pass the matching ID.`, "ORG_MISMATCH");
+		if (projectOrg && projectOrg !== inputs.orgId) throw new LinkInputError(`Project '${projectId}' belongs to organization '${projectOrg}', not '${inputs.orgId}'. Omit --org-id to use the project's own org, or pass the matching ID.`);
 		if (!projectOrg) await verifyOrgAccess(props, inputs.orgId);
 		return inputs.orgId;
 	}
@@ -309,20 +288,65 @@ const resolveOrgForProject = async (props, inputs, existing, projectId) => {
 	if (projectId === existing.projectId && existing.orgId) return existing.orgId;
 };
 /**
-* Resolve the branch to persist alongside a project in non-interactive mode.
-*
-* `link` never guesses the project's default branch — that's `checkout`'s job —
-* so the only sources are an explicit `--branch` (name or id, verified and
-* normalized to its name) or a branch already pinned for the *same* project (so
-* re-linking it doesn't drop your checked-out branch). Reading the existing
-* branch via {@link contextBranch} also recovers a legacy `branchId` field.
+* Keep an existing pin when re-linking the same project so `-y` does not reset
+* a checkout.
 */
 const resolvePinnedBranch = async (props, inputs, existing, projectId) => {
 	if (inputs.branch) {
 		const branch = await resolveBranchRef(props, projectId, inputs.branch);
-		return branchPersistValue(branch);
+		return {
+			branch: branchPersistValue(branch),
+			empty: false
+		};
+	}
+	if (projectId === existing.projectId) {
+		const pinned = contextBranch(existing);
+		if (pinned) return {
+			branch: pinned,
+			empty: false
+		};
+	}
+	return resolveBranchFromList(props, projectId);
+};
+const resolveBranchFromList = async (props, projectId) => {
+	const { data } = await props.apiClient.listProjectBranches({ projectId });
+	const branches = data.branches;
+	if (branches.length === 0) return { empty: true };
+	if (branches.length === 1) {
+		const [only] = branches;
+		if (!only) return { empty: true };
+		return {
+			branch: branchPersistValue(only),
+			empty: false
+		};
+	}
+	if (props.yes) {
+		const def = branches.find((b) => b.default);
+		if (!def) throw new Error(`Project '${projectId}' has no default branch. Pass --branch <name> to pin one.`);
+		return {
+			branch: branchPersistValue(def),
+			empty: false
+		};
 	}
-	if (projectId === existing.projectId) return contextBranch(existing);
+	if (canPromptInteractively()) {
+		const picked = await pickBranchInteractively(branches, {
+			message: "Which branch would you like to link?",
+			nonInteractiveMessage: `No branch could be selected without an interactive terminal. Re-run \`${getCliName()} link\` interactively, or \`${getCliName()} checkout <branch>\` to pin one.`
+		});
+		if (picked.kind === "existing") {
+			const existing = branches.find((b) => b.id === picked.branchId);
+			return {
+				branch: existing ? branchPersistValue(existing) : picked.branchId,
+				empty: false
+			};
+		}
+		await createBranch(props.apiClient, projectId, picked.name, branches);
+		return {
+			branch: picked.name,
+			empty: false
+		};
+	}
+	return { empty: false };
 };
 const runNonInteractive = async (props, inputs, existing) => {
 	if (inputs.projectName) {
@@ -351,36 +375,38 @@ const runNonInteractive = async (props, inputs, existing) => {
 	}
 	if (inputs.projectId) {
 		const orgId = await resolveOrgForProject(props, inputs, existing, inputs.projectId);
-		const branch = await resolvePinnedBranch(props, inputs, existing, inputs.projectId);
+		const resolved = await resolvePinnedBranch(props, inputs, existing, inputs.projectId);
 		applyContext(props.contextFile, {
 			orgId,
 			projectId: inputs.projectId,
-			branch
+			branch: resolved.branch
 		});
 		await finalizeLink(props, {
 			contextFile: props.contextFile,
 			orgId,
 			projectId: inputs.projectId,
-			branch,
-			created: false
+			branch: resolved.branch,
+			created: false,
+			empty: resolved.empty
 		});
 		return;
 	}
 	if (inputs.branch && existing.projectId) {
 		const projectId = existing.projectId;
 		const orgId = await resolveOrgForProject(props, inputs, existing, projectId);
-		const branch = await resolvePinnedBranch(props, inputs, existing, projectId);
+		const resolved = await resolvePinnedBranch(props, inputs, existing, projectId);
 		applyContext(props.contextFile, {
 			orgId,
 			projectId,
-			branch
+			branch: resolved.branch
 		});
 		await finalizeLink(props, {
 			contextFile: props.contextFile,
 			orgId,
 			projectId,
-			branch,
-			created: false
+			branch: resolved.branch,
+			created: false,
+			empty: resolved.empty
 		});
 		return;
 	}
@@ -439,20 +465,21 @@ const runInteractive = async (props, inputs) => {
 	const projects = await listAllProjects(props, orgId);
 	const action = await promptProjectChoice(projects, inputs.projectName);
 	if (action.type === "existing") {
-		const branch = await resolveInteractiveBranch(props, action.projectId);
+		const resolved = await resolveBranchFromList(props, action.projectId);
 		applyContext(props.contextFile, {
 			orgId,
 			projectId: action.projectId,
-			branch
+			branch: resolved.branch
 		});
 		await finalizeInteractiveLink(props, {
 			contextFile: props.contextFile,
 			orgId,
 			projectId: action.projectId,
-			branch,
+			branch: resolved.branch,
 			created: false,
 			projectName: action.name,
-			regionId: action.regionId
+			regionId: action.regionId,
+			empty: resolved.empty
 		});
 		return;
 	}
@@ -568,135 +595,6 @@ const promptRegion = async (props) => {
 	});
 	return regionId;
 };
-const runAgentSafely = async (props) => {
-	try {
-		const inputs = parseInputs(props);
-		validateInputs(inputs);
-		await runAgent(props, inputs);
-	} catch (err) {
-		emitAgent(toAgentError(err));
-		process.exit(1);
-	}
-};
-const runAgent = async (props, inputs) => {
-	const { projectId, projectName, regionId, branch } = inputs;
-	const existing = readContextFile(props.contextFile);
-	if (projectId) {
-		const orgId = await resolveOrgForProject(props, inputs, existing, projectId);
-		const pinnedBranch = await resolvePinnedBranch(props, inputs, existing, projectId);
-		applyContext(props.contextFile, {
-			orgId,
-			projectId,
-			branch: pinnedBranch
-		});
-		const orgSuffix = orgId ? ` (org ${orgId})` : "";
-		if (pinnedBranch) {
-			const pullNote = renderAgentPullNote(await autoPullEnvAfterPin({
-				...props,
-				projectId,
-				branch: pinnedBranch,
-				envPull: props.envPull
-			}));
-			emitAgent({
-				status: "linked",
-				context_file: props.contextFile,
-				context: {
-					orgId,
-					projectId,
-					branch: pinnedBranch
-				},
-				project: { id: projectId },
-				message: `Linked ${props.contextFile} to project ${projectId}${orgSuffix} on branch ${pinnedBranch}.${pullNote}`
-			});
-			return;
-		}
-		emitAgent({
-			status: "linked",
-			context_file: props.contextFile,
-			context: {
-				orgId,
-				projectId
-			},
-			project: { id: projectId },
-			message: `Linked ${props.contextFile} to project ${projectId}${orgSuffix}. No branch pinned — run \`${getCliName()} checkout <branch>\` (omit the branch to list options) to pin one and pull its env vars.`
-		});
-		return;
-	}
-	const orgResolution = await resolveOrg(props, inputs.orgId);
-	if (orgResolution.kind === "needs_selection") {
-		emitAgent(buildNeedsOrgResponse(orgResolution));
-		return;
-	}
-	const orgId = orgResolution.orgId;
-	if (projectName && !regionId) {
-		const regions = await fetchRegions(props);
-		emitAgent({
-			status: "needs_project_details",
-			instruction: `Ask the user which region to create project "${projectName}" in. After they pick one, re-run the next_command_template with the chosen --region-id value.`,
-			regions: regions.map((region) => ({
-				id: region.region_id,
-				name: region.name,
-				default: region.default
-			})),
-			next_command_template: `${getCliName()} link --agent --org-id ${shellArg(orgId)} --project-name ${shellArg(projectName)} --region-id <region_id>`
-		});
-		return;
-	}
-	if (projectName && regionId) {
-		await verifyOrgAccess(props, orgId);
-		const created = await createProject(props, {
-			orgId,
-			name: projectName,
-			regionId
-		});
-		applyContext(props.contextFile, {
-			orgId,
-			projectId: created.project.id,
-			branch: created.branchName
-		});
-		const pullNote = renderAgentPullNote(await autoPullEnvAfterPin({
-			...props,
-			projectId: created.project.id,
-			branch: created.branchName,
-			envPull: props.envPull
-		}));
-		emitAgent({
-			status: "linked",
-			context_file: props.contextFile,
-			context: {
-				orgId,
-				projectId: created.project.id,
-				branch: created.branchName
-			},
-			project: {
-				id: created.project.id,
-				name: created.project.name,
-				region_id: created.project.region_id
-			},
-			message: `Created project ${created.project.id} ("${created.project.name ?? projectName}") in ${created.project.region_id ?? regionId} and linked ${props.contextFile} on branch ${created.branchName}.${pullNote}`
-		});
-		return;
-	}
-	const projects = await listAllProjects(props, orgId);
-	const branchNote = branch ? ` A branch was requested (--branch ${branch}) but a branch can only be pinned once a project is chosen — re-run with --project-id first, then \`${getCliName()} checkout ${branch}\`.` : "";
-	emitAgent({
-		status: "needs_project",
-		instruction: (projects.length === 0 ? `Organization ${orgId} has no projects yet. Ask the user for a name for the new project, then re-run the create_option.next_command_template.` : `Ask the user whether to link to one of these ${projects.length} existing projects (use next_command_template with --project-id) or create a new project (use create_option.next_command_template).`) + branchNote,
-		options: projects.map((project) => ({
-			id: project.id,
-			name: project.name,
-			region_id: project.region_id
-		})),
-		create_option: {
-			instruction: "To create a new project, ask the user for a project name. The region can be omitted to receive a follow-up needs_project_details response that lists available regions.",
-			next_command_template: `${getCliName()} link --agent --org-id ${shellArg(orgId)} --project-name <name> --region-id <region_id>`
-		},
-		next_command_template: `${getCliName()} link --agent --org-id ${shellArg(orgId)} --project-id <project_id>`
-	});
-};
-const emitAgent = (response) => {
-	process.stdout.write(`${JSON.stringify(response, null, 2)}\n`);
-};
 const ORG_KEY_LIMITED_FRAGMENT = "not allowed for organization API keys";
 const isOrgKeyLimitedError = (err) => {
 	if (!isNeonApiError(err)) return false;
@@ -754,56 +652,6 @@ const detectOrgIdFromProjects = async (props) => {
 		return;
 	}
 };
-const buildNeedsOrgResponse = (resolution) => {
-	if (resolution.orgKeyLimited) return {
-		status: "needs_org",
-		instruction: "This Neon API key is organization-scoped, so the CLI cannot list the user's organizations and no existing project was found to auto-detect the org ID. Ask the user for their Neon organization ID (visible in the Neon Console under the org's Settings page, formatted like `org-bitter-breeze-12345678`) and re-run the next_command_template with that --org-id.",
-		options: [],
-		next_command_template: `${getCliName()} link --agent --org-id <org_id>`
-	};
-	const orgs = resolution.orgs;
-	return {
-		status: "needs_org",
-		instruction: orgs.length === 0 ? "The user does not belong to any organizations. Ask them to create one in the Neon Console (https://console.neon.tech/) before linking." : `Ask the user which of these ${orgs.length} organization${orgs.length === 1 ? "" : "s"} they want to link the current directory to. After they pick one, re-run the next_command_template with the chosen --org-id value.`,
-		options: orgs.map((org) => ({
-			id: org.id,
-			name: org.name
-		})),
-		next_command_template: `${getCliName()} link --agent --org-id <org_id>`
-	};
-};
-const toAgentError = (err) => {
-	if (err instanceof LinkInputError) return {
-		status: "error",
-		code: err.agentCode,
-		message: err.message
-	};
-	if (isNeonApiError(err)) {
-		const status = err.status;
-		const apiMessage = messageFromBody(err.data);
-		const message = apiMessage !== void 0 && apiMessage.length > 0 ? apiMessage : err.message;
-		let code = "API_ERROR";
-		if (status === 401 || status === 403) code = "AUTH_ERROR";
-		else if (status !== void 0 && status >= 400 && status < 500) code = "CLIENT_ERROR";
-		else if (status !== void 0 && status >= 500) code = "SERVER_ERROR";
-		else if (err.code === "ECONNABORTED") code = "TIMEOUT";
-		return {
-			status: "error",
-			code,
-			message
-		};
-	}
-	if (err instanceof Error) return {
-		status: "error",
-		code: "INTERNAL_ERROR",
-		message: err.message
-	};
-	return {
-		status: "error",
-		code: "INTERNAL_ERROR",
-		message: String(err)
-	};
-};
 const listAllProjects = async (props, orgId) => {
 	const result = [];
 	let cursor;
@@ -819,33 +667,6 @@ const listAllProjects = async (props, orgId) => {
 	}
 	return result;
 };
-/**
-* Resolve which branch to pin for an interactively-chosen project, returned as the value to
-* persist (its name when known, see {@link branchPersistValue}). When the project has a
-* single branch there is nothing to choose, so we pin it silently. Otherwise we offer the
-* shared branch picker (the same "＋ Create a new branch…" + list as `neonctl checkout`),
-* creating the branch when the user opts to. This makes interactive `link` a full org →
-* project → branch flow; non-interactive `link` instead defers the branch to `checkout`.
-*/
-const resolveInteractiveBranch = async (props, projectId) => {
-	const { data } = await props.apiClient.listProjectBranches({ projectId });
-	const branches = data.branches;
-	if (branches.length <= 1) {
-		const only = branches.find((b) => b.default) ?? branches[0];
-		if (!only) throw new Error(`Could not find a default branch for project ${projectId}.`);
-		return branchPersistValue(only);
-	}
-	const picked = await pickBranchInteractively(branches, {
-		message: "Which branch would you like to link?",
-		nonInteractiveMessage: `No branch could be selected without an interactive terminal. Re-run \`${getCliName()} link\` interactively, or \`${getCliName()} checkout <branch>\` to pin one.`
-	});
-	if (picked.kind === "existing") {
-		const existing = branches.find((b) => b.id === picked.branchId);
-		return existing ? branchPersistValue(existing) : picked.branchId;
-	}
-	await createBranch(props.apiClient, projectId, picked.name, branches);
-	return picked.name;
-};
 const fetchRegions = async (props) => {
 	try {
 		const { data } = await props.apiClient.getActiveRegions();
@@ -897,7 +718,8 @@ const printSummary = (_props, summary) => {
 		lines.push("Written offline (--no-checks): nothing was verified.");
 	} else if (summary.projectId && !summary.branch && !summary.orgOnly) {
 		lines.push("");
-		lines.push(`No branch pinned. Run \`${getCliName()} checkout <branch>\` to pin a branch and pull its env vars.`);
+		if (summary.empty) lines.push(`This project has no branches, so none was pinned. Create a branch, then run \`${getCliName()} checkout <branch>\` to pin it and pull its env vars.`);
+		else lines.push(`No branch pinned. Run \`${getCliName()} checkout <branch>\` to pin a branch and pull its env vars.`);
 	}
 	lines.push("");
 	process.stdout.write(`${lines.join("\n")}\n`);
@@ -965,10 +787,6 @@ const onPromptState = (state) => {
 		process.exit(1);
 	}
 };
-const shellArg = (value) => {
-	if (/^[A-Za-z0-9._:/-]+$/.test(value)) return value;
-	return `'${value.replace(/'/g, `'\\''`)}'`;
-};
 const mustString = (value, name) => {
 	if (value === void 0) throw new Error(`Internal error: expected ${name} to be set.`);
 	return value;

package/dist/commands/mcp.js

@@ -4,13 +4,13 @@ import { readContextFile } from "../context.js";
 import { getCliName } from "../utils/cli_name.js";
 import { writer } from "../writer.js";
 import { noPassthrough, single } from "../utils/flags.js";
+import { canPickAgentsInteractively } from "../utils/agent_picker.js";
+import { helpCsv, helpEpilogue } from "../utils/help_text.js";
 import { NEON_MCP_CATEGORIES, NEON_MCP_URL, existingNeonApiKey, installNeonMcpServer, neonMcpUrl, parseMcpCategories, trackedProjectMcpConfig } from "../mcp/install.js";
 import { mintMcpApiKey, mintedKeyRevokeCommand, withdrawMintedKey } from "../mcp/mint.js";
-import { canPickAgentsInteractively } from "../utils/agent_picker.js";
 import { mcpInstallableAgents, resolveInstallTargets } from "../mcp/targets.js";
 import { confirmMcpInstall } from "../mcp/wizard.js";
 import { resolveMcpPlan } from "../mcp/plan.js";
-import { helpCsv, helpEpilogue } from "../utils/help_text.js";
 //#region src/commands/mcp.ts
 var mcp_exports = /* @__PURE__ */ __exportAll({
 	builder: () => builder,

package/dist/commands/plugins.js

@@ -2,14 +2,14 @@ import { t as __exportAll } from "../_chunks/rolldown-runtime-8H4AJuhK.js";
 import { log } from "../log.js";
 import { writer } from "../writer.js";
 import { noPassthrough } from "../utils/flags.js";
-import { NEON_MCP_URL } from "../mcp/install.js";
 import { getAgentDisplayName } from "../mcp/agents.js";
 import "../init/agents.js";
+import { pluginsInstallableAgents } from "../plugins/targets.js";
 import { canPickAgentsInteractively } from "../utils/agent_picker.js";
+import { NEON_PLUGIN_NAME, PLUGIN_SKILLS, PLUGIN_SOURCE, neonPluginsRetryCommand, pluginsAddArgs, runPluginsCli } from "../plugins/run.js";
 import { helpCsv, helpEpilogue } from "../utils/help_text.js";
-import { pluginsInstallableAgents } from "../plugins/targets.js";
+import { NEON_MCP_URL } from "../mcp/install.js";
 import { resolvePluginsPlan } from "../plugins/plan.js";
-import { NEON_PLUGIN_NAME, PLUGIN_SKILLS, PLUGIN_SOURCE, neonPluginsRetryCommand, pluginsAddArgs, runPluginsCli } from "../plugins/run.js";
 import { confirmPluginsInstall } from "../plugins/wizard.js";
 //#region src/commands/plugins.ts
 var plugins_exports = /* @__PURE__ */ __exportAll({

package/dist/commands/profile.js

@@ -1,14 +1,14 @@
 import { t as __exportAll } from "../_chunks/rolldown-runtime-8H4AJuhK.js";
 import { t as writeSecretFile } from "../_chunks/secure_file-BucZj4yQ.js";
-import { c as describeScope, d as scopeOf, l as interpretCredentials, n as KEYRING_SERVICE, o as apiKeyCredentials, r as keyringAccount, s as credentialLabel, t as storeFor } from "../_chunks/credential_io-B1JxWELN.js";
+import { c as describeScope, d as scopeOf, l as interpretCredentials, n as KEYRING_SERVICE, o as apiKeyCredentials, r as keyringAccount, s as credentialLabel, t as storeFor } from "../_chunks/credential_io-YeAxg9Xn.js";
 import { isCi } from "../env.js";
 import { log } from "../log.js";
 import { getApiClient, isNeonApiError } from "../api.js";
-import { o as isOwnedCredentialPath, r as credentialsPath } from "../_chunks/paths-g3DRqJiD.js";
+import { a as isOwnedCredentialPath, n as credentialsPath } from "../_chunks/paths-DMq0Lt7a.js";
 import { setAuthContext } from "../auth_context.js";
-import { _ as upsertProfile, a as canDropProfilesFile, c as listProfiles, d as newProfileLocation, f as profilesFilePath, g as selectProfileName, h as resolveProfile, i as assertValidProfileName, l as locationForName, m as readProfiles, n as KEYRING_CREDENTIALS, o as credentialsDisplay, p as profilesUsingPath, r as assertProfilesUsable, s as isKeyringPointer, u as locationOf, v as CRED_STORAGE_FILE, y as CRED_STORAGE_KEYRING } from "../_chunks/profiles-D95AeZ5v.js";
+import { _ as upsertProfile, a as canDropProfilesFile, c as listProfiles, d as newProfileLocation, f as profilesFilePath, g as selectProfileName, h as resolveProfile, i as assertValidProfileName, l as locationForName, m as readProfiles, n as KEYRING_CREDENTIALS, o as credentialsDisplay, p as profilesUsingPath, r as assertProfilesUsable, s as isKeyringPointer, u as locationOf, v as CRED_STORAGE_FILE, y as CRED_STORAGE_KEYRING } from "../_chunks/profiles-CvnFEQyd.js";
 import { auth, revokeToken } from "../auth.js";
-import { t as credentialInputs } from "../_chunks/auth_selection-ktL6uoEe.js";
+import { t as credentialInputs } from "../_chunks/auth_selection-pitMFzDe.js";
 import { readOutgoingCredential, retirePreviousCredential, revokeTokenSet, withdrawKey } from "../retire_credential.js";
 import { authFlow, usableCredential } from "./auth.js";
 import { writer } from "../writer.js";

package/dist/config.js

@@ -1,5 +1,5 @@
 import { isCi } from "./env.js";
-import { a as isInsideConfigDir, i as defaultDir, o as isOwnedCredentialPath, r as credentialsPath, t as CREDENTIALS_FILE } from "./_chunks/paths-g3DRqJiD.js";
+import { a as isOwnedCredentialPath, i as isInsideConfigDir, n as credentialsPath, r as defaultDir, t as CREDENTIALS_FILE } from "./_chunks/paths-DMq0Lt7a.js";
 import { existsSync, mkdirSync } from "node:fs";
 //#region src/config.ts
 const ensureConfigDir = ({ "config-dir": configDirArg, "force-auth": forceAuth }) => {

package/dist/credential_io.js

@@ -1,2 +1,2 @@
-import { t as storeFor } from "./_chunks/credential_io-B1JxWELN.js";
+import { t as storeFor } from "./_chunks/credential_io-YeAxg9Xn.js";
 export { storeFor };