neon 4.7.0 → 4.9.0

package/dist/init/orchestrate.js

@@ -1,189 +0,0 @@
-import { tryResolveAddMcpAgentId } from "../mcp/agents.js";
-import { supportsSkills } from "./agents.js";
-import { isAuthenticated } from "./auth.js";
-import { inspectProject } from "./inspect.js";
-import { getSkillList, missingSkillsForAgent, skillsInstalledForAgent } from "./skills.js";
-import { handleAuthPhase } from "./phases/auth.js";
-import { handleGettingStartedPhase } from "./phases/getting_started.js";
-import { handleMigrationsPhase } from "./phases/migrations.js";
-import { handleNeonAuthPhase } from "./phases/neon_auth.js";
-import { handleSetupPhase } from "./phases/setup.js";
-import { resolveNeonContext } from "./resolve_context.js";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
-//#region src/init/orchestrate.ts
-/**
-* v2 orchestrator: checks phases in order and returns the first that needs attention.
-*
-* Phase order:
-*   auth -> setup (if tooling not installed)
-*        -> getting-started (if tooling installed but no Neon connection string)
-*        -> resolve .neon context (if connection string exists but no .neon file)
-*        -> neon_auth (optional) -> complete
-*
-* Each call is stateless — it re-checks everything from the file system and credentials.
-*
-* The orchestrator uses filesystem inspection to decide what to do:
-* - No app detected → bootstrap phase (scaffold from template)
-* - MCP not configured → full setup flow (inspect → install → getting-started)
-* - MCP configured, no connection string → skip install, go to getting-started
-* - MCP configured + connection string → fall through to neon-auth/migrations/complete
-*/
-async function orchestrate(options) {
-	if (!await isAuthenticated()) return handleAuthPhase({ agent: options.agent });
-	const cwd = process.cwd();
-	const inspection = await inspectProject([
-		{
-			id: "has_app",
-			description: "",
-			lookFor: []
-		},
-		{
-			id: "mcp_server",
-			description: "",
-			lookFor: []
-		},
-		{
-			id: "skills",
-			description: "",
-			lookFor: []
-		},
-		{
-			id: "connection_string",
-			description: "",
-			lookFor: []
-		},
-		{
-			id: "project_stack",
-			description: "",
-			lookFor: []
-		},
-		{
-			id: "migrations",
-			description: "",
-			lookFor: []
-		}
-	]);
-	const hasApp = options.preview ? inspection.hasApp === true : true;
-	const requestedAgent = options.agent ? tryResolveAddMcpAgentId(options.agent) : void 0;
-	let skillsInstalled = inspection.skillsInstalled;
-	if (options.preview && requestedAgent && supportsSkills(requestedAgent)) {
-		const missing = missingSkillsForAgent(requestedAgent, {
-			cwd,
-			preview: true
-		});
-		const required = getSkillList(true);
-		if (missing.length > 0) {
-			skillsInstalled = false;
-			if (missing.length < required.length) inspection.skillsScope = `${inspection.skillsScope && !String(inspection.skillsScope).includes("partial") ? inspection.skillsScope : "project"}-partial`;
-		}
-	} else if (options.preview && skillsInstalled && inspection.skillsScope) {
-		const previewSkills = getSkillList(true);
-		const { existsSync: exists } = await import("node:fs");
-		const { resolve: resolvePath } = await import("node:path");
-		const home = process.env.HOME || process.env.USERPROFILE || "";
-		const dirs = inspection.skillsScope === "project" ? [
-			resolvePath(cwd, ".cursor", "skills"),
-			resolvePath(cwd, ".claude", "skills"),
-			resolvePath(cwd, ".agents", "skills")
-		] : [
-			resolvePath(home, ".cursor", "skills"),
-			resolvePath(home, ".claude", "skills"),
-			resolvePath(home, ".agents", "skills")
-		];
-		if (!previewSkills.every((skill) => dirs.some((dir) => exists(resolvePath(dir, skill, "SKILL.md"))))) {
-			skillsInstalled = false;
-			inspection.skillsScope = `${inspection.skillsScope}-partial`;
-		}
-	}
-	const mcpForThisAgent = requestedAgent ? (inspection.mcpAgents ?? []).some((hit) => hit.agent === requestedAgent) : inspection.mcpConfigured === true;
-	const skillsReady = requestedAgent && !supportsSkills(requestedAgent) ? true : requestedAgent ? skillsInstalledForAgent(requestedAgent, cwd, options.preview) : skillsInstalled === true;
-	const toolingInstalled = mcpForThisAgent && skillsReady;
-	const hasNeonConnection = inspection.connectionString === true;
-	if (!hasApp || !toolingInstalled) {
-		cleanupInitState(resolve(cwd, ".neon"));
-		return handleSetupPhase({
-			agent: options.agent,
-			preview: options.preview,
-			hasApp,
-			mcpConfigured: requestedAgent ? mcpForThisAgent : inspection.mcpConfigured ?? null,
-			mcpScope: inspection.mcpScope || void 0,
-			skillsInstalled: requestedAgent ? skillsReady : skillsInstalled ?? null,
-			skillsScope: inspection.skillsScope || void 0
-		});
-	}
-	const neonContextPath = resolve(cwd, ".neon");
-	const neonContext = readNeonContext(neonContextPath);
-	const initState = typeof neonContext._init === "object" && neonContext._init !== null ? neonContext._init : {};
-	const features = Array.isArray(initState.features) ? initState.features : [];
-	if (!hasNeonConnection) return handleGettingStartedPhase({
-		agent: options.agent,
-		cwd,
-		hasConnectionString: false,
-		framework: inspection.framework,
-		orm: inspection.orm,
-		migrationTool: inspection.migrationTool,
-		migrationDir: inspection.migrationDir,
-		features,
-		preview: options.preview
-	});
-	if (!neonContext.projectId) try {
-		const resolved = await resolveNeonContext(cwd);
-		if (resolved) {
-			const merged = { ...neonContext };
-			if (resolved.orgId) merged.orgId = resolved.orgId;
-			if (resolved.projectId) merged.projectId = resolved.projectId;
-			writeFileSync(neonContextPath, `${JSON.stringify(merged, null, 2)}\n`);
-		}
-	} catch {}
-	if (features.includes("auth")) {
-		if (!checkNeonAuth(cwd)) return handleNeonAuthPhase({
-			agent: options.agent,
-			setup: true
-		});
-	}
-	if (!options.skipMigrations) return handleMigrationsPhase({
-		agent: options.agent,
-		cwd
-	});
-	cleanupInitState(neonContextPath);
-	return {
-		phase: "setup",
-		status: "complete",
-		nextAction: {
-			type: "complete",
-			message: requestedAgent && !supportsSkills(requestedAgent) ? "Neon setup is complete. Your database is configured and your agent has the Neon MCP server available." : "Neon setup is complete. Your database is configured and your agent has the Neon MCP server and skills available."
-		}
-	};
-}
-/** Remove the ephemeral _init key from .neon, preserving other fields. */
-function cleanupInitState(neonContextPath) {
-	if (!existsSync(neonContextPath)) return;
-	try {
-		const context = JSON.parse(readFileSync(neonContextPath, "utf-8"));
-		if (context._init !== void 0) {
-			delete context._init;
-			writeFileSync(neonContextPath, `${JSON.stringify(context, null, 2)}\n`);
-		}
-	} catch {}
-}
-function readNeonContext(neonContextPath) {
-	if (!existsSync(neonContextPath)) return {};
-	try {
-		return JSON.parse(readFileSync(neonContextPath, "utf-8"));
-	} catch {
-		return {};
-	}
-}
-function checkNeonAuth(cwd) {
-	const envPath = resolve(cwd, ".env");
-	if (!existsSync(envPath)) return false;
-	try {
-		const content = readFileSync(envPath, "utf-8");
-		return /^NEON_AUTH_/m.test(content);
-	} catch {
-		return false;
-	}
-}
-//#endregion
-export { orchestrate };

package/dist/init/phases/auth.js

@@ -1,195 +0,0 @@
-import { isAuthenticated } from "../auth.js";
-import { neonctlCmd } from "../neonctl.js";
-//#region src/init/phases/auth.ts
-function getSignupUrl() {
-	return process.env.NEON_API_HOST ? `${new URL(process.env.NEON_API_HOST).origin}/signup` : "https://console.neon.tech/signup";
-}
-function getSignupCommands() {
-	const url = getSignupUrl();
-	return {
-		darwin: `open ${url}`,
-		linux: `xdg-open ${url}`,
-		win32: `start ${url}`
-	};
-}
-async function handleAuthPhase(options) {
-	const agentArgs = options.agent ? [
-		"--agent",
-		options.agent,
-		"--json"
-	] : ["--json"];
-	if (options.verify) {
-		if (await isAuthenticated()) return {
-			phase: "auth",
-			status: "verified",
-			nextAction: {
-				type: "run_neon_init",
-				args: agentArgs
-			}
-		};
-		return {
-			phase: "auth",
-			status: "not_authenticated",
-			nextAction: {
-				type: "run_neon_init",
-				args: ["auth", "--json"]
-			}
-		};
-	}
-	if (await isAuthenticated()) return {
-		phase: "auth",
-		status: "verified",
-		nextAction: {
-			type: "run_neon_init",
-			args: agentArgs
-		}
-	};
-	if (options.method === "new") return {
-		phase: "auth",
-		status: "in_progress",
-		nextAction: {
-			type: "agent_action",
-			steps: [{
-				id: "open_signup",
-				description: "Open the Neon sign-up page in the user's browser",
-				command: getSignupCommands()[process.platform] ?? getSignupCommands().linux
-			}, {
-				id: "wait_for_signup",
-				description: "Tell the user: 'I've opened the Neon sign-up page. Create your account and verify your email, then let me know when you're ready.'"
-			}],
-			onComplete: {
-				type: "run_neon_init",
-				args: [
-					"auth",
-					"--json",
-					"--method",
-					"existing"
-				]
-			}
-		}
-	};
-	if (options.method === "existing") return {
-		phase: "auth",
-		status: "in_progress",
-		nextAction: {
-			type: "run_command",
-			command: `${neonctlCmd()} auth`,
-			description: "This will open your browser for Neon OAuth sign-in.",
-			timeout: 12e4,
-			onSuccess: {
-				type: "run_neon_init",
-				args: [
-					"auth",
-					"--json",
-					"--verify"
-				]
-			},
-			onFailure: {
-				"2": {
-					type: "ask_user",
-					question: "The sign-in timed out. Did you complete the sign-in in your browser?",
-					options: ["yes_retry", "need_help"],
-					responseMapping: {
-						yes_retry: { args: [
-							"auth",
-							"--json",
-							"--method",
-							"existing"
-						] },
-						need_help: { args: [
-							"auth",
-							"--json",
-							"--method",
-							"new"
-						] }
-					}
-				},
-				other: {
-					type: "run_neon_init",
-					args: ["auth", "--json"]
-				}
-			}
-		}
-	};
-	const openCmd = getSignupCommands()[process.platform] ?? getSignupCommands().linux;
-	return {
-		phase: "auth",
-		status: "required",
-		nextAction: {
-			type: "ask_user",
-			instructions: "IMPORTANT: You MUST present this question to the user and WAIT for their response before proceeding. Do NOT assume the answer or auto-select an option. The user's answer determines the next step.",
-			question: "Do you have an existing Neon account, or do you need to create one?",
-			options: [{
-				value: "existing_account",
-				label: "I have an existing Neon account"
-			}, {
-				value: "new_account",
-				label: "I need to create a new account"
-			}],
-			context: "Neon is a complete set of cloud backend primitives built around Lakebase Postgres. A free account is required to continue.",
-			responseMapping: {
-				existing_account: { action: {
-					type: "run_command",
-					command: `${neonctlCmd()} auth`,
-					description: "This will open your browser for Neon OAuth sign-in.",
-					timeout: 12e4,
-					onSuccess: {
-						type: "run_neon_init",
-						args: [
-							"auth",
-							"--json",
-							"--verify"
-						]
-					},
-					onFailure: {
-						"2": {
-							type: "ask_user",
-							question: "The sign-in timed out. Did you complete the sign-in in your browser?",
-							options: ["yes_retry", "need_help"],
-							responseMapping: {
-								yes_retry: { args: [
-									"auth",
-									"--json",
-									"--method",
-									"existing"
-								] },
-								need_help: { args: [
-									"auth",
-									"--json",
-									"--method",
-									"new"
-								] }
-							}
-						},
-						other: {
-							type: "run_neon_init",
-							args: ["auth", "--json"]
-						}
-					}
-				} },
-				new_account: { action: {
-					type: "agent_action",
-					steps: [{
-						id: "open_signup",
-						description: "Open the Neon sign-up page in the user's browser",
-						command: openCmd
-					}, {
-						id: "wait_for_signup",
-						description: "Tell the user: 'I've opened the Neon sign-up page. Create your account and verify your email, then let me know when you're ready.'"
-					}],
-					onComplete: {
-						type: "run_neon_init",
-						args: [
-							"auth",
-							"--json",
-							"--method",
-							"existing"
-						]
-					}
-				} }
-			}
-		}
-	};
-}
-//#endregion
-export { handleAuthPhase };

package/dist/init/phases/cleanup.js

@@ -1,27 +0,0 @@
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
-//#region src/init/phases/cleanup.ts
-/**
-* Terminal phase: cleans up ephemeral _init state from .neon and
-* returns a complete message. All feature chains should end here.
-*/
-function handleCleanup() {
-	const neonContextPath = resolve(process.cwd(), ".neon");
-	if (existsSync(neonContextPath)) try {
-		const context = JSON.parse(readFileSync(neonContextPath, "utf-8"));
-		if (context._init !== void 0) {
-			delete context._init;
-			writeFileSync(neonContextPath, `${JSON.stringify(context, null, 2)}\n`);
-		}
-	} catch {}
-	return {
-		phase: "setup",
-		status: "complete",
-		nextAction: {
-			type: "complete",
-			message: "Neon setup is complete! Your database is connected and your agent has the Neon MCP server and skills available."
-		}
-	};
-}
-//#endregion
-export { handleCleanup };

package/dist/init/phases/db.js

@@ -1,257 +0,0 @@
-import { neonctlCmd } from "../neonctl.js";
-import { SKILL_REFERENCE_URLS } from "../skills.js";
-//#region src/init/phases/db.ts
-/**
-* Validates that an ID contains only safe characters for shell interpolation.
-* Neon org/project IDs are typically UUIDs or slug-like strings.
-*/
-function assertSafeId(value, label) {
-	if (!/^[\w.:-]+$/.test(value)) throw new Error(`Invalid ${label}: "${value}". Expected alphanumeric, hyphens, underscores, dots, or colons.`);
-}
-async function handleDbPhase(options) {
-	const agentArgs = options.agent ? [
-		"--agent",
-		options.agent,
-		"--json"
-	] : ["--json"];
-	if (options.projectId) assertSafeId(options.projectId, "project ID");
-	if (options.orgId) assertSafeId(options.orgId, "org ID");
-	if (options.error) return {
-		phase: "db",
-		status: "error",
-		error: options.error,
-		nextAction: {
-			type: "ask_user",
-			question: `An error occurred during database setup: ${options.error}. Would you like to try again or skip this step?`,
-			options: [{
-				value: "retry",
-				label: "Try again"
-			}, {
-				value: "skip",
-				label: "Skip database setup"
-			}],
-			responseMapping: {
-				retry: { args: ["db", "--json"] },
-				skip: { args: agentArgs }
-			}
-		}
-	};
-	if (options.projectId) return {
-		phase: "db",
-		status: "project_ready",
-		project: { id: options.projectId },
-		nextAction: {
-			type: "agent_action",
-			prerequisite: SKILL_REFERENCE_URLS.connectionMethods,
-			steps: [
-				{
-					id: "get_connection_string",
-					description: "Get the database connection string",
-					command: `${neonctlCmd()} connection-string --project-id ${options.projectId}`
-				},
-				{
-					id: "store_env",
-					description: "Append DATABASE_URL=<connection_string> to .env. Create .env if it doesn't exist. Do NOT overwrite existing entries. Ensure .env is in .gitignore."
-				},
-				{
-					id: "detect_framework",
-					description: "Examine the project to determine the framework (Next.js, Remix, Express, etc.) and ORM (Prisma, Drizzle, raw SQL) in use."
-				}
-			],
-			onComplete: {
-				type: "run_neon_init",
-				args: agentArgs
-			}
-		}
-	};
-	if (options.projectsResult) {
-		let projects;
-		try {
-			const parsed = JSON.parse(options.projectsResult);
-			projects = Array.isArray(parsed.projects) ? parsed.projects : Array.isArray(parsed) ? parsed : [];
-		} catch {
-			projects = [];
-		}
-		const orgIdArgs = options.orgId ? ["--org-id", options.orgId] : [];
-		if (projects.length === 0) return {
-			phase: "db",
-			status: "no_projects",
-			nextAction: {
-				type: "ask_user",
-				question: "You don't have any Neon projects yet. What would you like to name your new project?",
-				options: [{
-					value: "create",
-					label: "Create a new project (provide a name)"
-				}],
-				context: `The agent should ask the user for a project name, then run: ${neonctlCmd()} projects create --name <name> --output json` + (options.orgId ? ` --org-id ${options.orgId}` : "") + " and pass the result back.",
-				responseMapping: { create: { args: [
-					"db",
-					"--json",
-					...orgIdArgs,
-					"--project-id",
-					"<created-project-id>"
-				] } }
-			}
-		};
-		const projectOptions = projects.map((p) => ({
-			value: p.id,
-			label: `${p.name} (${p.id})`
-		}));
-		projectOptions.push({
-			value: "create_new",
-			label: "Create a new project"
-		});
-		const responseMapping = {};
-		for (const p of projects) responseMapping[p.id] = { args: [
-			"db",
-			"--json",
-			...orgIdArgs,
-			"--project-id",
-			p.id
-		] };
-		responseMapping.create_new = { args: [
-			"db",
-			"--json",
-			...orgIdArgs,
-			"--project-id",
-			"<created-project-id>"
-		] };
-		return {
-			phase: "db",
-			status: "select_project",
-			nextAction: {
-				type: "ask_user",
-				question: "Which Neon project would you like to use?",
-				options: projectOptions,
-				context: `If the user wants to create a new project, ask for a name then run: ${neonctlCmd()} projects create --name <name> --output json and use the returned project id.`,
-				responseMapping
-			}
-		};
-	}
-	if (options.orgsResult) {
-		let orgs;
-		try {
-			const parsed = JSON.parse(options.orgsResult);
-			orgs = Array.isArray(parsed.organizations) ? parsed.organizations : Array.isArray(parsed) ? parsed : [];
-		} catch {
-			orgs = [];
-		}
-		const orgId = options.orgId ?? (orgs.length === 1 ? orgs[0].id : null);
-		if (orgId) {
-			assertSafeId(orgId, "org ID");
-			return {
-				phase: "db",
-				status: "org_selected",
-				org: { id: orgId },
-				nextAction: {
-					type: "run_command",
-					command: `${neonctlCmd()} projects list --org-id ${orgId} --output json`,
-					description: "Listing Neon projects.",
-					timeout: 3e4,
-					onSuccess: {
-						type: "run_neon_init",
-						args: [
-							"db",
-							"--json",
-							"--org-id",
-							orgId,
-							"--projects-result",
-							"<stdout>"
-						]
-					},
-					onFailure: { other: {
-						type: "run_neon_init",
-						args: [
-							"db",
-							"--json",
-							"--error",
-							"projects-list-failed"
-						]
-					} }
-				}
-			};
-		}
-		const orgOptions = orgs.map((o) => ({
-			value: o.id,
-			label: `${o.name} (${o.id})`
-		}));
-		const responseMapping = {};
-		for (const o of orgs) responseMapping[o.id] = { args: [
-			"db",
-			"--json",
-			"--org-id",
-			o.id
-		] };
-		return {
-			phase: "db",
-			status: "select_org",
-			nextAction: {
-				type: "ask_user",
-				question: "Which Neon organization would you like to use?",
-				options: orgOptions,
-				responseMapping
-			}
-		};
-	}
-	if (options.orgId) return {
-		phase: "db",
-		status: "org_selected",
-		org: { id: options.orgId },
-		nextAction: {
-			type: "run_command",
-			command: `${neonctlCmd()} projects list --org-id ${options.orgId} --output json`,
-			description: "Listing Neon projects.",
-			timeout: 3e4,
-			onSuccess: {
-				type: "run_neon_init",
-				args: [
-					"db",
-					"--json",
-					"--org-id",
-					options.orgId,
-					"--projects-result",
-					"<stdout>"
-				]
-			},
-			onFailure: { other: {
-				type: "run_neon_init",
-				args: [
-					"db",
-					"--json",
-					"--error",
-					"projects-list-failed"
-				]
-			} }
-		}
-	};
-	return {
-		phase: "db",
-		status: "ready",
-		nextAction: {
-			type: "run_command",
-			command: `${neonctlCmd()} orgs list --output json`,
-			description: "Listing your Neon organizations.",
-			timeout: 3e4,
-			onSuccess: {
-				type: "run_neon_init",
-				args: [
-					"db",
-					"--json",
-					"--orgs-result",
-					"<stdout>"
-				]
-			},
-			onFailure: { other: {
-				type: "run_neon_init",
-				args: [
-					"db",
-					"--json",
-					"--error",
-					"orgs-list-failed"
-				]
-			} }
-		}
-	};
-}
-//#endregion
-export { handleDbPhase };