neon-init 0.14.0 → 0.16.0

package/dist/lib/neonctl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"neonctl.js","names":[],"sources":["../../src/lib/neonctl.ts"],"sourcesContent":["import { execa } from \"execa\";\n\n/**\n * Derives --api-host and --oauth-host flags from the NEON_API_HOST env var.\n *\n * When NEON_API_HOST is set (e.g. \"https://console-stage.neon.build\"), neonctl\n * commands need explicit flags:\n *   --api-host https://console-stage.neon.build/api/v2\n *   --oauth-host https://oauth2-stage.neon.build\n *\n * The oauth host is derived by replacing the \"console\" prefix in the hostname\n * with \"oauth2\" (e.g. console-stage.neon.build → oauth2-stage.neon.build).\n */\nexport function getNeonctlApiFlags(): string {\n\tconst apiHost = process.env.NEON_API_HOST;\n\tif (!apiHost) return \"\";\n\n\tconst apiUrl = `${apiHost.replace(/\\/+$/, \"\")}/api/v2`;\n\n\tlet oauthUrl = \"\";\n\ttry {\n\t\tconst url = new URL(apiHost);\n\t\turl.hostname = url.hostname.replace(/^console/, \"oauth2\");\n\t\t// OAuth host is just the origin (no path)\n\t\toauthUrl = url.origin;\n\t} catch {\n\t\t// If URL parsing fails, skip oauth-host\n\t}\n\n\tconst flags = [`--api-host ${apiUrl}`];\n\tif (oauthUrl) flags.push(`--oauth-host ${oauthUrl}`);\n\treturn flags.join(\" \");\n}\n\n/**\n * Returns the neonctl command prefix: \"CI= npx -y neonctl\" with any\n * --api-host / --oauth-host flags appended when NEON_API_HOST is set.\n *\n * Usage: `${neonctlCmd()} orgs list --output json`\n */\nexport function neonctlCmd(): string {\n\tconst flags = getNeonctlApiFlags();\n\treturn flags ? `CI= npx -y neonctl ${flags}` : \"CI= npx -y neonctl\";\n}\n\n/**\n * Detects which package manager was used to invoke the current process.\n * Reads the `npm_config_user_agent` env var set by npm/pnpm/yarn/bun when\n * they spawn child processes (including via `npx`, `pnpx`, `bunx`, etc.).\n *\n * Falls back to \"npm\" if detection fails.\n */\nexport function detectPackageManager(): \"npm\" | \"pnpm\" | \"yarn\" | \"bun\" {\n\tconst ua = process.env.npm_config_user_agent;\n\tif (ua) {\n\t\tif (ua.startsWith(\"pnpm/\")) return \"pnpm\";\n\t\tif (ua.startsWith(\"yarn/\")) return \"yarn\";\n\t\tif (ua.startsWith(\"bun/\")) return \"bun\";\n\t}\n\treturn \"npm\";\n}\n\n/**\n * Returns the global install command for a given package manager.\n */\nfunction globalInstallArgs(\n\tpm: \"npm\" | \"pnpm\" | \"yarn\" | \"bun\",\n\tpkg: string,\n): { command: string; args: string[] } {\n\tswitch (pm) {\n\t\tcase \"pnpm\":\n\t\t\treturn { command: \"pnpm\", args: [\"add\", \"-g\", pkg] };\n\t\tcase \"yarn\":\n\t\t\treturn { command: \"yarn\", args: [\"global\", \"add\", pkg] };\n\t\tcase \"bun\":\n\t\t\treturn { command: \"bun\", args: [\"add\", \"-g\", pkg] };\n\t\tdefault:\n\t\t\treturn { command: \"npm\", args: [\"install\", \"-g\", pkg] };\n\t}\n}\n\ninterface NeonctlStatus {\n\tinstalled: boolean;\n\tcurrentVersion: string | null;\n\tlatestVersion: string | null;\n\tneedsUpdate: boolean;\n}\n\n/**\n * Gets the currently available neonctl version.\n * Tries the global binary first, then falls back to npx.\n */\nasync function getNeonctlVersion(): Promise<string | null> {\n\t// Try global binary first (fast path)\n\ttry {\n\t\tconst result = await execa(\"neonctl\", [\"--version\"], {\n\t\t\tstdio: \"pipe\",\n\t\t\ttimeout: 5000,\n\t\t});\n\t\tconst match = result.stdout.trim().match(/(\\d+\\.\\d+\\.\\d+)/);\n\t\tif (match) return match[1];\n\t} catch {\n\t\t// Not globally installed — that's fine\n\t}\n\treturn null;\n}\n\n/**\n * Checks whether the neonctl CLI is globally installed and whether it's up to date.\n */\nexport async function checkNeonctl(): Promise<NeonctlStatus> {\n\tconst currentVersion = await getNeonctlVersion();\n\n\tif (!currentVersion) {\n\t\treturn {\n\t\t\tinstalled: false,\n\t\t\tcurrentVersion: null,\n\t\t\tlatestVersion: null,\n\t\t\tneedsUpdate: true,\n\t\t};\n\t}\n\n\t// Check latest version from npm registry\n\tlet latestVersion: string | null = null;\n\ttry {\n\t\tconst result = await execa(\"npm\", [\"view\", \"neonctl\", \"version\"], {\n\t\t\tstdio: \"pipe\",\n\t\t\ttimeout: 10000,\n\t\t});\n\t\tlatestVersion = result.stdout.trim();\n\t} catch {\n\t\t// Can't determine latest — assume current is fine\n\t\treturn {\n\t\t\tinstalled: true,\n\t\t\tcurrentVersion,\n\t\t\tlatestVersion: null,\n\t\t\tneedsUpdate: false,\n\t\t};\n\t}\n\n\tconst needsUpdate =\n\t\tcurrentVersion !== null &&\n\t\tlatestVersion !== null &&\n\t\tcurrentVersion !== latestVersion &&\n\t\tisOlderVersion(currentVersion, latestVersion);\n\n\treturn { installed: true, currentVersion, latestVersion, needsUpdate };\n}\n\nfunction isOlderVersion(current: string, latest: string): boolean {\n\tconst c = current.split(\".\").map(Number);\n\tconst l = latest.split(\".\").map(Number);\n\tfor (let i = 0; i < 3; i++) {\n\t\tif ((c[i] ?? 0) < (l[i] ?? 0)) return true;\n\t\tif ((c[i] ?? 0) > (l[i] ?? 0)) return false;\n\t}\n\treturn false;\n}\n\nexport interface EnsureNeonctlResult {\n\tstatus: \"already_current\" | \"installed\" | \"updated\" | \"failed\";\n\tversion?: string;\n\terror?: string;\n}\n\n/**\n * Ensures neonctl is globally installed and up to date.\n * Uses the same package manager that invoked the init command.\n */\nexport async function ensureNeonctl(): Promise<EnsureNeonctlResult> {\n\tconst check = await checkNeonctl();\n\n\tif (check.installed && !check.needsUpdate) {\n\t\treturn {\n\t\t\tstatus: \"already_current\",\n\t\t\tversion: check.currentVersion ?? undefined,\n\t\t};\n\t}\n\n\tconst pm = detectPackageManager();\n\tconst { command, args } = globalInstallArgs(pm, \"neonctl\");\n\n\ttry {\n\t\tawait execa(command, args, { stdio: \"pipe\", timeout: 60000 });\n\n\t\t// Verify installation\n\t\tconst version = await getNeonctlVersion();\n\t\treturn {\n\t\t\tstatus: check.installed ? \"updated\" : \"installed\",\n\t\t\tversion: version ?? undefined,\n\t\t};\n\t} catch (err) {\n\t\treturn {\n\t\t\tstatus: \"failed\",\n\t\t\terror: err instanceof Error ? err.message : \"Unknown error\",\n\t\t};\n\t}\n}\n"],"mappings":"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"}

package/dist/lib/phases/auth.d.ts

@@ -0,0 +1,12 @@
+import { PhaseResponse } from "../types.js";
+
+//#region src/lib/phases/auth.d.ts
+interface AuthPhaseOptions {
+  agent?: string;
+  method?: "existing" | "new";
+  verify?: boolean;
+}
+declare function handleAuthPhase(options: AuthPhaseOptions): Promise<PhaseResponse>;
+//#endregion
+export { AuthPhaseOptions, handleAuthPhase };
+//# sourceMappingURL=auth.d.ts.map

package/dist/lib/phases/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","names":[],"sources":["../../../src/lib/phases/auth.ts"],"mappings":";;;UAkBiB,gBAAA;;EAAA,MAAA,CAAA,EAAA,UAAgB,GAAA,KAAA;EAMX,MAAA,CAAA,EAAA,OAAA;;AACZ,iBADY,eAAA,CACZ,OAAA,EAAA,gBAAA,CAAA,EACP,OADO,CACC,aADD,CAAA"}

package/dist/lib/phases/auth.js

@@ -0,0 +1,197 @@
+import { isAuthenticated } from "../auth.js";
+import { neonctlCmd } from "../neonctl.js";
+//#region src/lib/phases/auth.ts
+function getSignupUrl() {
+	const base = process.env.NEON_API_HOST?.replace(/\/+$/, "");
+	return base ? `${base}/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",
+			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 serverless Postgres provider. 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 };
+
+//# sourceMappingURL=auth.js.map

package/dist/lib/phases/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","names":[],"sources":["../../../src/lib/phases/auth.ts"],"sourcesContent":["import { isAuthenticated } from \"../auth.js\";\nimport { neonctlCmd } from \"../neonctl.js\";\nimport type { PhaseResponse } from \"../types.js\";\n\nfunction getSignupUrl(): string {\n\tconst base = process.env.NEON_API_HOST?.replace(/\\/+$/, \"\");\n\treturn base ? `${base}/signup` : \"https://console.neon.tech/signup\";\n}\n\nfunction getSignupCommands(): Record<string, string> {\n\tconst url = getSignupUrl();\n\treturn {\n\t\tdarwin: `open ${url}`,\n\t\tlinux: `xdg-open ${url}`,\n\t\twin32: `start ${url}`,\n\t};\n}\n\nexport interface AuthPhaseOptions {\n\tagent?: string;\n\tmethod?: \"existing\" | \"new\";\n\tverify?: boolean;\n}\n\nexport async function handleAuthPhase(\n\toptions: AuthPhaseOptions,\n): Promise<PhaseResponse> {\n\tconst agentArgs = options.agent\n\t\t? [\"--agent\", options.agent, \"--json\"]\n\t\t: [\"--json\"];\n\n\t// --verify: just check if credentials exist\n\tif (options.verify) {\n\t\tconst authed = await isAuthenticated();\n\t\tif (authed) {\n\t\t\t// Continue the flow immediately — don't use \"complete\" which\n\t\t\t// causes agents to stop and get distracted by neonctl output.\n\t\t\treturn {\n\t\t\t\tphase: \"auth\",\n\t\t\t\tstatus: \"verified\",\n\t\t\t\tnextAction: {\n\t\t\t\t\ttype: \"run_neon_init\",\n\t\t\t\t\targs: agentArgs,\n\t\t\t\t},\n\t\t\t};\n\t\t}\n\t\treturn {\n\t\t\tphase: \"auth\",\n\t\t\tstatus: \"not_authenticated\",\n\t\t\tnextAction: {\n\t\t\t\ttype: \"run_neon_init\",\n\t\t\t\targs: [\"auth\", \"--json\"],\n\t\t\t},\n\t\t};\n\t}\n\n\t// Check if already authenticated\n\tconst authed = await isAuthenticated();\n\tif (authed) {\n\t\treturn {\n\t\t\tphase: \"auth\",\n\t\t\tstatus: \"verified\",\n\t\t\tnextAction: {\n\t\t\t\ttype: \"run_neon_init\",\n\t\t\t\targs: agentArgs,\n\t\t\t},\n\t\t};\n\t}\n\n\t// --method new: guide through signup\n\tif (options.method === \"new\") {\n\t\tconst openCmd =\n\t\t\tgetSignupCommands()[process.platform] ?? getSignupCommands().linux;\n\t\treturn {\n\t\t\tphase: \"auth\",\n\t\t\tstatus: \"in_progress\",\n\t\t\tnextAction: {\n\t\t\t\ttype: \"agent_action\",\n\t\t\t\tsteps: [\n\t\t\t\t\t{\n\t\t\t\t\t\tid: \"open_signup\",\n\t\t\t\t\t\tdescription:\n\t\t\t\t\t\t\t\"Open the Neon sign-up page in the user's browser\",\n\t\t\t\t\t\tcommand: openCmd,\n\t\t\t\t\t},\n\t\t\t\t\t{\n\t\t\t\t\t\tid: \"wait_for_signup\",\n\t\t\t\t\t\tdescription:\n\t\t\t\t\t\t\t\"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.'\",\n\t\t\t\t\t},\n\t\t\t\t],\n\t\t\t\tonComplete: {\n\t\t\t\t\ttype: \"run_neon_init\",\n\t\t\t\t\targs: [\"auth\", \"--json\", \"--method\", \"existing\"],\n\t\t\t\t},\n\t\t\t},\n\t\t};\n\t}\n\n\t// --method existing: run OAuth flow\n\tif (options.method === \"existing\") {\n\t\treturn {\n\t\t\tphase: \"auth\",\n\t\t\tstatus: \"in_progress\",\n\t\t\tnextAction: {\n\t\t\t\ttype: \"run_command\",\n\t\t\t\tcommand: `${neonctlCmd()} auth`,\n\t\t\t\tdescription:\n\t\t\t\t\t\"This will open your browser for Neon OAuth sign-in.\",\n\t\t\t\ttimeout: 120000,\n\t\t\t\tonSuccess: {\n\t\t\t\t\ttype: \"run_neon_init\",\n\t\t\t\t\targs: [\"auth\", \"--json\", \"--verify\"],\n\t\t\t\t},\n\t\t\t\tonFailure: {\n\t\t\t\t\t\"2\": {\n\t\t\t\t\t\ttype: \"ask_user\",\n\t\t\t\t\t\tquestion:\n\t\t\t\t\t\t\t\"The sign-in timed out. Did you complete the sign-in in your browser?\",\n\t\t\t\t\t\toptions: [\"yes_retry\", \"need_help\"],\n\t\t\t\t\t\tresponseMapping: {\n\t\t\t\t\t\t\tyes_retry: {\n\t\t\t\t\t\t\t\targs: [\n\t\t\t\t\t\t\t\t\t\"auth\",\n\t\t\t\t\t\t\t\t\t\"--json\",\n\t\t\t\t\t\t\t\t\t\"--method\",\n\t\t\t\t\t\t\t\t\t\"existing\",\n\t\t\t\t\t\t\t\t],\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\tneed_help: {\n\t\t\t\t\t\t\t\targs: [\"auth\", \"--json\", \"--method\", \"new\"],\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t},\n\t\t\t\t\t},\n\t\t\t\t\tother: {\n\t\t\t\t\t\ttype: \"run_neon_init\",\n\t\t\t\t\t\targs: [\"auth\", \"--json\"],\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t},\n\t\t};\n\t}\n\n\t// No method specified: ask the user, then launch OAuth directly for\n\t// \"existing account\" without an intermediate CLI round-trip.\n\tconst openCmd =\n\t\tgetSignupCommands()[process.platform] ?? getSignupCommands().linux;\n\treturn {\n\t\tphase: \"auth\",\n\t\tstatus: \"required\",\n\t\tnextAction: {\n\t\t\ttype: \"ask_user\",\n\t\t\tquestion:\n\t\t\t\t\"Do you have an existing Neon account, or do you need to create one?\",\n\t\t\toptions: [\n\t\t\t\t{\n\t\t\t\t\tvalue: \"existing_account\",\n\t\t\t\t\tlabel: \"I have an existing Neon account\",\n\t\t\t\t},\n\t\t\t\t{\n\t\t\t\t\tvalue: \"new_account\",\n\t\t\t\t\tlabel: \"I need to create a new account\",\n\t\t\t\t},\n\t\t\t],\n\t\t\tcontext:\n\t\t\t\t\"Neon is a serverless Postgres provider. A free account is required to continue.\",\n\t\t\tresponseMapping: {\n\t\t\t\texisting_account: {\n\t\t\t\t\taction: {\n\t\t\t\t\t\ttype: \"run_command\",\n\t\t\t\t\t\tcommand: `${neonctlCmd()} auth`,\n\t\t\t\t\t\tdescription:\n\t\t\t\t\t\t\t\"This will open your browser for Neon OAuth sign-in.\",\n\t\t\t\t\t\ttimeout: 120000,\n\t\t\t\t\t\tonSuccess: {\n\t\t\t\t\t\t\ttype: \"run_neon_init\",\n\t\t\t\t\t\t\targs: [\"auth\", \"--json\", \"--verify\"],\n\t\t\t\t\t\t},\n\t\t\t\t\t\tonFailure: {\n\t\t\t\t\t\t\t\"2\": {\n\t\t\t\t\t\t\t\ttype: \"ask_user\",\n\t\t\t\t\t\t\t\tquestion:\n\t\t\t\t\t\t\t\t\t\"The sign-in timed out. Did you complete the sign-in in your browser?\",\n\t\t\t\t\t\t\t\toptions: [\"yes_retry\", \"need_help\"],\n\t\t\t\t\t\t\t\tresponseMapping: {\n\t\t\t\t\t\t\t\t\tyes_retry: {\n\t\t\t\t\t\t\t\t\t\targs: [\n\t\t\t\t\t\t\t\t\t\t\t\"auth\",\n\t\t\t\t\t\t\t\t\t\t\t\"--json\",\n\t\t\t\t\t\t\t\t\t\t\t\"--method\",\n\t\t\t\t\t\t\t\t\t\t\t\"existing\",\n\t\t\t\t\t\t\t\t\t\t],\n\t\t\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t\t\tneed_help: {\n\t\t\t\t\t\t\t\t\t\targs: [\n\t\t\t\t\t\t\t\t\t\t\t\"auth\",\n\t\t\t\t\t\t\t\t\t\t\t\"--json\",\n\t\t\t\t\t\t\t\t\t\t\t\"--method\",\n\t\t\t\t\t\t\t\t\t\t\t\"new\",\n\t\t\t\t\t\t\t\t\t\t],\n\t\t\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\tother: {\n\t\t\t\t\t\t\t\ttype: \"run_neon_init\",\n\t\t\t\t\t\t\t\targs: [\"auth\", \"--json\"],\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t},\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t\tnew_account: {\n\t\t\t\t\taction: {\n\t\t\t\t\t\ttype: \"agent_action\",\n\t\t\t\t\t\tsteps: [\n\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\tid: \"open_signup\",\n\t\t\t\t\t\t\t\tdescription:\n\t\t\t\t\t\t\t\t\t\"Open the Neon sign-up page in the user's browser\",\n\t\t\t\t\t\t\t\tcommand: openCmd,\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\tid: \"wait_for_signup\",\n\t\t\t\t\t\t\t\tdescription:\n\t\t\t\t\t\t\t\t\t\"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.'\",\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t],\n\t\t\t\t\t\tonComplete: {\n\t\t\t\t\t\t\ttype: \"run_neon_init\",\n\t\t\t\t\t\t\targs: [\"auth\", \"--json\", \"--method\", \"existing\"],\n\t\t\t\t\t\t},\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t},\n\t\t},\n\t};\n}\n"],"mappings":"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"}

package/dist/lib/phases/cleanup.d.ts

@@ -0,0 +1,12 @@
+import { PhaseResponse } from "../types.js";
+
+//#region src/lib/phases/cleanup.d.ts
+
+/**
+ * Terminal phase: cleans up ephemeral _init state from .neon and
+ * returns a complete message. All feature chains should end here.
+ */
+declare function handleCleanup(): PhaseResponse;
+//#endregion
+export { handleCleanup };
+//# sourceMappingURL=cleanup.d.ts.map

package/dist/lib/phases/cleanup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup.d.ts","names":[],"sources":["../../../src/lib/phases/cleanup.ts"],"mappings":";;;;;;AAQA;;iBAAgB,aAAA,CAAA,GAAiB"}

package/dist/lib/phases/cleanup.js

@@ -0,0 +1,29 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+//#region src/lib/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 };
+
+//# sourceMappingURL=cleanup.js.map

package/dist/lib/phases/cleanup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup.js","names":[],"sources":["../../../src/lib/phases/cleanup.ts"],"sourcesContent":["import { existsSync, readFileSync, writeFileSync } from \"node:fs\";\nimport { resolve } from \"node:path\";\nimport type { PhaseResponse } from \"../types.js\";\n\n/**\n * Terminal phase: cleans up ephemeral _init state from .neon and\n * returns a complete message. All feature chains should end here.\n */\nexport function handleCleanup(): PhaseResponse {\n\tconst neonContextPath = resolve(process.cwd(), \".neon\");\n\tif (existsSync(neonContextPath)) {\n\t\ttry {\n\t\t\tconst context = JSON.parse(readFileSync(neonContextPath, \"utf-8\"));\n\t\t\tif (context._init !== undefined) {\n\t\t\t\tdelete context._init;\n\t\t\t\twriteFileSync(\n\t\t\t\t\tneonContextPath,\n\t\t\t\t\t`${JSON.stringify(context, null, 2)}\\n`,\n\t\t\t\t);\n\t\t\t}\n\t\t} catch {}\n\t}\n\n\treturn {\n\t\tphase: \"setup\",\n\t\tstatus: \"complete\",\n\t\tnextAction: {\n\t\t\ttype: \"complete\",\n\t\t\tmessage:\n\t\t\t\t\"Neon setup is complete! Your database is connected and your agent has the Neon MCP server and skills available.\",\n\t\t},\n\t};\n}\n"],"mappings":";;;;;;;AAQA,SAAgB,gBAA+B;CAC9C,MAAM,kBAAkB,QAAQ,QAAQ,IAAI,GAAG,OAAO;CACtD,IAAI,WAAW,eAAe,GAC7B,IAAI;EACH,MAAM,UAAU,KAAK,MAAM,aAAa,iBAAiB,OAAO,CAAC;EACjE,IAAI,QAAQ,UAAU,KAAA,GAAW;GAChC,OAAO,QAAQ;GACf,cACC,iBACA,GAAG,KAAK,UAAU,SAAS,MAAM,CAAC,EAAE,GACrC;EACD;CACD,QAAQ,CAAC;CAGV,OAAO;EACN,OAAO;EACP,QAAQ;EACR,YAAY;GACX,MAAM;GACN,SACC;EACF;CACD;AACD"}

package/dist/lib/phases/db.d.ts

@@ -0,0 +1,17 @@
+import { PhaseResponse } from "../types.js";
+
+//#region src/lib/phases/db.d.ts
+interface DbPhaseOptions {
+  agent?: string;
+  orgId?: string;
+  projectId?: string;
+  orgsResult?: string;
+  projectsResult?: string;
+  framework?: string;
+  orm?: string;
+  error?: string;
+}
+declare function handleDbPhase(options: DbPhaseOptions): Promise<PhaseResponse>;
+//#endregion
+export { DbPhaseOptions, handleDbPhase };
+//# sourceMappingURL=db.d.ts.map

package/dist/lib/phases/db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.d.ts","names":[],"sources":["../../../src/lib/phases/db.ts"],"mappings":";;;UAgBiB,cAAA;;EAAA,KAAA,CAAA,EAAA,MAAA;EAWK,SAAA,CAAA,EAAA,MAAa;EAAA,UAAA,CAAA,EAAA,MAAA;gBACzB,CAAA,EAAA,MAAA;WACC,CAAA,EAAA,MAAA;KAAR,CAAA,EAAA,MAAA;EAAO,KAAA,CAAA,EAAA,MAAA;;iBAFY,aAAA,UACZ,iBACP,QAAQ"}

package/dist/lib/phases/db.js

@@ -0,0 +1,259 @@
+import { neonctlCmd } from "../neonctl.js";
+import { SKILL_REFERENCE_URLS } from "../skills.js";
+//#region src/lib/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 };
+
+//# sourceMappingURL=db.js.map

package/dist/lib/phases/db.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.js","names":[],"sources":["../../../src/lib/phases/db.ts"],"sourcesContent":["import { neonctlCmd } from \"../neonctl.js\";\nimport { SKILL_REFERENCE_URLS } from \"../skills.js\";\nimport type { PhaseResponse } from \"../types.js\";\n\n/**\n * Validates that an ID contains only safe characters for shell interpolation.\n * Neon org/project IDs are typically UUIDs or slug-like strings.\n */\nfunction assertSafeId(value: string, label: string): void {\n\tif (!/^[\\w.:-]+$/.test(value)) {\n\t\tthrow new Error(\n\t\t\t`Invalid ${label}: \"${value}\". Expected alphanumeric, hyphens, underscores, dots, or colons.`,\n\t\t);\n\t}\n}\n\nexport interface DbPhaseOptions {\n\tagent?: string;\n\torgId?: string;\n\tprojectId?: string;\n\torgsResult?: string;\n\tprojectsResult?: string;\n\tframework?: string;\n\torm?: string;\n\terror?: string;\n}\n\nexport async function handleDbPhase(\n\toptions: DbPhaseOptions,\n): Promise<PhaseResponse> {\n\tconst agentArgs = options.agent\n\t\t? [\"--agent\", options.agent, \"--json\"]\n\t\t: [\"--json\"];\n\n\t// Validate IDs that will be interpolated into shell commands\n\tif (options.projectId) assertSafeId(options.projectId, \"project ID\");\n\tif (options.orgId) assertSafeId(options.orgId, \"org ID\");\n\n\t// Error from a previous step\n\tif (options.error) {\n\t\treturn {\n\t\t\tphase: \"db\",\n\t\t\tstatus: \"error\",\n\t\t\terror: options.error,\n\t\t\tnextAction: {\n\t\t\t\ttype: \"ask_user\",\n\t\t\t\tquestion: `An error occurred during database setup: ${options.error}. Would you like to try again or skip this step?`,\n\t\t\t\toptions: [\n\t\t\t\t\t{ value: \"retry\", label: \"Try again\" },\n\t\t\t\t\t{ value: \"skip\", label: \"Skip database setup\" },\n\t\t\t\t],\n\t\t\t\tresponseMapping: {\n\t\t\t\t\tretry: { args: [\"db\", \"--json\"] },\n\t\t\t\t\tskip: { args: agentArgs },\n\t\t\t\t},\n\t\t\t},\n\t\t};\n\t}\n\n\t// If we have a project ID, we're in the \"wire it up\" phase\n\tif (options.projectId) {\n\t\treturn {\n\t\t\tphase: \"db\",\n\t\t\tstatus: \"project_ready\",\n\t\t\tproject: { id: options.projectId },\n\t\t\tnextAction: {\n\t\t\t\ttype: \"agent_action\",\n\t\t\t\tprerequisite: SKILL_REFERENCE_URLS.connectionMethods,\n\t\t\t\tsteps: [\n\t\t\t\t\t{\n\t\t\t\t\t\tid: \"get_connection_string\",\n\t\t\t\t\t\tdescription: \"Get the database connection string\",\n\t\t\t\t\t\tcommand: `${neonctlCmd()} connection-string --project-id ${options.projectId}`,\n\t\t\t\t\t},\n\t\t\t\t\t{\n\t\t\t\t\t\tid: \"store_env\",\n\t\t\t\t\t\tdescription:\n\t\t\t\t\t\t\t\"Append DATABASE_URL=<connection_string> to .env. Create .env if it doesn't exist. Do NOT overwrite existing entries. Ensure .env is in .gitignore.\",\n\t\t\t\t\t},\n\t\t\t\t\t{\n\t\t\t\t\t\tid: \"detect_framework\",\n\t\t\t\t\t\tdescription:\n\t\t\t\t\t\t\t\"Examine the project to determine the framework (Next.js, Remix, Express, etc.) and ORM (Prisma, Drizzle, raw SQL) in use.\",\n\t\t\t\t\t},\n\t\t\t\t],\n\t\t\t\tonComplete: {\n\t\t\t\t\ttype: \"run_neon_init\",\n\t\t\t\t\targs: agentArgs,\n\t\t\t\t},\n\t\t\t},\n\t\t};\n\t}\n\n\t// If we have projects result, let user pick or create\n\tif (options.projectsResult) {\n\t\tlet projects: { id: string; name: string }[];\n\t\ttry {\n\t\t\tconst parsed = JSON.parse(options.projectsResult);\n\t\t\tprojects = Array.isArray(parsed.projects)\n\t\t\t\t? parsed.projects\n\t\t\t\t: Array.isArray(parsed)\n\t\t\t\t\t? parsed\n\t\t\t\t\t: [];\n\t\t} catch {\n\t\t\tprojects = [];\n\t\t}\n\n\t\tconst orgIdArgs = options.orgId ? [\"--org-id\", options.orgId] : [];\n\n\t\tif (projects.length === 0) {\n\t\t\treturn {\n\t\t\t\tphase: \"db\",\n\t\t\t\tstatus: \"no_projects\",\n\t\t\t\tnextAction: {\n\t\t\t\t\ttype: \"ask_user\",\n\t\t\t\t\tquestion:\n\t\t\t\t\t\t\"You don't have any Neon projects yet. What would you like to name your new project?\",\n\t\t\t\t\toptions: [\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tvalue: \"create\",\n\t\t\t\t\t\t\tlabel: \"Create a new project (provide a name)\",\n\t\t\t\t\t\t},\n\t\t\t\t\t],\n\t\t\t\t\tcontext:\n\t\t\t\t\t\t`The agent should ask the user for a project name, then run: ${neonctlCmd()} projects create --name <name> --output json` +\n\t\t\t\t\t\t(options.orgId ? ` --org-id ${options.orgId}` : \"\") +\n\t\t\t\t\t\t\" and pass the result back.\",\n\t\t\t\t\tresponseMapping: {\n\t\t\t\t\t\tcreate: {\n\t\t\t\t\t\t\targs: [\n\t\t\t\t\t\t\t\t\"db\",\n\t\t\t\t\t\t\t\t\"--json\",\n\t\t\t\t\t\t\t\t...orgIdArgs,\n\t\t\t\t\t\t\t\t\"--project-id\",\n\t\t\t\t\t\t\t\t\"<created-project-id>\",\n\t\t\t\t\t\t\t],\n\t\t\t\t\t\t},\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t};\n\t\t}\n\n\t\tconst projectOptions = projects.map((p) => ({\n\t\t\tvalue: p.id,\n\t\t\tlabel: `${p.name} (${p.id})`,\n\t\t}));\n\t\tprojectOptions.push({\n\t\t\tvalue: \"create_new\",\n\t\t\tlabel: \"Create a new project\",\n\t\t});\n\n\t\tconst responseMapping: Record<string, { args: string[] }> = {};\n\t\tfor (const p of projects) {\n\t\t\tresponseMapping[p.id] = {\n\t\t\t\targs: [\"db\", \"--json\", ...orgIdArgs, \"--project-id\", p.id],\n\t\t\t};\n\t\t}\n\t\tresponseMapping.create_new = {\n\t\t\targs: [\n\t\t\t\t\"db\",\n\t\t\t\t\"--json\",\n\t\t\t\t...orgIdArgs,\n\t\t\t\t\"--project-id\",\n\t\t\t\t\"<created-project-id>\",\n\t\t\t],\n\t\t};\n\n\t\treturn {\n\t\t\tphase: \"db\",\n\t\t\tstatus: \"select_project\",\n\t\t\tnextAction: {\n\t\t\t\ttype: \"ask_user\",\n\t\t\t\tquestion: \"Which Neon project would you like to use?\",\n\t\t\t\toptions: projectOptions,\n\t\t\t\tcontext: `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.`,\n\t\t\t\tresponseMapping,\n\t\t\t},\n\t\t};\n\t}\n\n\t// If we have orgs result, decide next step\n\tif (options.orgsResult) {\n\t\tlet orgs: { id: string; name: string }[];\n\t\ttry {\n\t\t\tconst parsed = JSON.parse(options.orgsResult);\n\t\t\torgs = Array.isArray(parsed.organizations)\n\t\t\t\t? parsed.organizations\n\t\t\t\t: Array.isArray(parsed)\n\t\t\t\t\t? parsed\n\t\t\t\t\t: [];\n\t\t} catch {\n\t\t\torgs = [];\n\t\t}\n\n\t\t// Single org or org already selected: list projects\n\t\tconst orgId = options.orgId ?? (orgs.length === 1 ? orgs[0].id : null);\n\n\t\tif (orgId) {\n\t\t\tassertSafeId(orgId, \"org ID\");\n\t\t\treturn {\n\t\t\t\tphase: \"db\",\n\t\t\t\tstatus: \"org_selected\",\n\t\t\t\torg: { id: orgId },\n\t\t\t\tnextAction: {\n\t\t\t\t\ttype: \"run_command\",\n\t\t\t\t\tcommand: `${neonctlCmd()} projects list --org-id ${orgId} --output json`,\n\t\t\t\t\tdescription: \"Listing Neon projects.\",\n\t\t\t\t\ttimeout: 30000,\n\t\t\t\t\tonSuccess: {\n\t\t\t\t\t\ttype: \"run_neon_init\",\n\t\t\t\t\t\targs: [\n\t\t\t\t\t\t\t\"db\",\n\t\t\t\t\t\t\t\"--json\",\n\t\t\t\t\t\t\t\"--org-id\",\n\t\t\t\t\t\t\torgId,\n\t\t\t\t\t\t\t\"--projects-result\",\n\t\t\t\t\t\t\t\"<stdout>\",\n\t\t\t\t\t\t],\n\t\t\t\t\t},\n\t\t\t\t\tonFailure: {\n\t\t\t\t\t\tother: {\n\t\t\t\t\t\t\ttype: \"run_neon_init\",\n\t\t\t\t\t\t\targs: [\n\t\t\t\t\t\t\t\t\"db\",\n\t\t\t\t\t\t\t\t\"--json\",\n\t\t\t\t\t\t\t\t\"--error\",\n\t\t\t\t\t\t\t\t\"projects-list-failed\",\n\t\t\t\t\t\t\t],\n\t\t\t\t\t\t},\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t};\n\t\t}\n\n\t\t// Multiple orgs: ask user to pick\n\t\tconst orgOptions = orgs.map((o) => ({\n\t\t\tvalue: o.id,\n\t\t\tlabel: `${o.name} (${o.id})`,\n\t\t}));\n\t\tconst responseMapping: Record<string, { args: string[] }> = {};\n\t\tfor (const o of orgs) {\n\t\t\tresponseMapping[o.id] = {\n\t\t\t\targs: [\"db\", \"--json\", \"--org-id\", o.id],\n\t\t\t};\n\t\t}\n\n\t\treturn {\n\t\t\tphase: \"db\",\n\t\t\tstatus: \"select_org\",\n\t\t\tnextAction: {\n\t\t\t\ttype: \"ask_user\",\n\t\t\t\tquestion: \"Which Neon organization would you like to use?\",\n\t\t\t\toptions: orgOptions,\n\t\t\t\tresponseMapping,\n\t\t\t},\n\t\t};\n\t}\n\n\t// If org-id provided but no orgs-result, list projects directly\n\tif (options.orgId) {\n\t\treturn {\n\t\t\tphase: \"db\",\n\t\t\tstatus: \"org_selected\",\n\t\t\torg: { id: options.orgId },\n\t\t\tnextAction: {\n\t\t\t\ttype: \"run_command\",\n\t\t\t\tcommand: `${neonctlCmd()} projects list --org-id ${options.orgId} --output json`,\n\t\t\t\tdescription: \"Listing Neon projects.\",\n\t\t\t\ttimeout: 30000,\n\t\t\t\tonSuccess: {\n\t\t\t\t\ttype: \"run_neon_init\",\n\t\t\t\t\targs: [\n\t\t\t\t\t\t\"db\",\n\t\t\t\t\t\t\"--json\",\n\t\t\t\t\t\t\"--org-id\",\n\t\t\t\t\t\toptions.orgId,\n\t\t\t\t\t\t\"--projects-result\",\n\t\t\t\t\t\t\"<stdout>\",\n\t\t\t\t\t],\n\t\t\t\t},\n\t\t\t\tonFailure: {\n\t\t\t\t\tother: {\n\t\t\t\t\t\ttype: \"run_neon_init\",\n\t\t\t\t\t\targs: [\n\t\t\t\t\t\t\t\"db\",\n\t\t\t\t\t\t\t\"--json\",\n\t\t\t\t\t\t\t\"--error\",\n\t\t\t\t\t\t\t\"projects-list-failed\",\n\t\t\t\t\t\t],\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t},\n\t\t};\n\t}\n\n\t// Default: start by listing orgs\n\treturn {\n\t\tphase: \"db\",\n\t\tstatus: \"ready\",\n\t\tnextAction: {\n\t\t\ttype: \"run_command\",\n\t\t\tcommand: `${neonctlCmd()} orgs list --output json`,\n\t\t\tdescription: \"Listing your Neon organizations.\",\n\t\t\ttimeout: 30000,\n\t\t\tonSuccess: {\n\t\t\t\ttype: \"run_neon_init\",\n\t\t\t\targs: [\"db\", \"--json\", \"--orgs-result\", \"<stdout>\"],\n\t\t\t},\n\t\t\tonFailure: {\n\t\t\t\tother: {\n\t\t\t\t\ttype: \"run_neon_init\",\n\t\t\t\t\targs: [\"db\", \"--json\", \"--error\", \"orgs-list-failed\"],\n\t\t\t\t},\n\t\t\t},\n\t\t},\n\t};\n}\n"],"mappings":"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"}

package/dist/lib/phases/getting-started.d.ts

@@ -0,0 +1,26 @@
+import { PhaseResponse } from "../types.js";
+
+//#region src/lib/phases/getting-started.d.ts
+interface GettingStartedPhaseOptions {
+  agent?: string;
+  hasConnectionString?: boolean;
+  framework?: string;
+  orm?: string;
+  migrationTool?: string;
+  migrationDir?: string;
+  /** Neon features required by the project (from .neon or template) */
+  features?: string[];
+  /** Preview mode — restricts project creation to new projects in AWS us-east */
+  preview?: boolean;
+}
+/**
+ * Initiates the "Get started with Neon" workflow.
+ *
+ * Steps are concrete and executable — each has a CLI command to run
+ * or a specific file operation. The agent should attempt each step
+ * in order and actually perform the action using the neonctl CLI.
+ */
+declare function handleGettingStartedPhase(options: GettingStartedPhaseOptions): Promise<PhaseResponse>;
+//#endregion
+export { GettingStartedPhaseOptions, handleGettingStartedPhase };
+//# sourceMappingURL=getting-started.d.ts.map

package/dist/lib/phases/getting-started.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getting-started.d.ts","names":[],"sources":["../../../src/lib/phases/getting-started.ts"],"mappings":";;;UAIiB,0BAAA;;EAAA,mBAAA,CAAA,EAAA,OAA0B;EAoBrB,SAAA,CAAA,EAAA,MAAA;EAAyB,GAAA,CAAA,EAAA,MAAA;eACrC,CAAA,EAAA,MAAA;cACC,CAAA,EAAA,MAAA;;EAAD,QAAA,CAAA,EAAA,MAAA,EAAA;;;;;;;;;;;iBAFY,yBAAA,UACZ,6BACP,QAAQ"}