neon-init 0.13.1 → 0.15.0

package/dist/lib/phases/db.js

@@ -0,0 +1,258 @@
+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: `CI= npx -y neonctl 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: CI= npx -y neonctl 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: CI= npx -y neonctl 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: `CI= npx -y neonctl 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: `CI= npx -y neonctl 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: "CI= npx -y neonctl 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 { 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: `CI= npx -y neonctl 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: CI= npx -y neonctl 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:\n\t\t\t\t\t\"If the user wants to create a new project, ask for a name then run: CI= npx -y neonctl 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: `CI= npx -y neonctl 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: `CI= npx -y neonctl 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: \"CI= npx -y neonctl 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":";;;UAGiB,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"}

package/dist/lib/phases/getting-started.js

@@ -0,0 +1,195 @@
+import { SKILL_REFERENCE_URLS, ensureSkillsUpToDate } from "../skills.js";
+//#region src/lib/phases/getting-started.ts
+/**
+* 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.
+*/
+async function handleGettingStartedPhase(options) {
+	if (options.agent) await ensureSkillsUpToDate(options.agent);
+	const steps = [];
+	if (!options.hasConnectionString) {
+		if (options.preview) steps.push({
+			id: "select_org",
+			description: [
+				"List the user's Neon organizations using the CLI command below.",
+				"If only one org exists, use it automatically.",
+				"If multiple orgs exist, ask the user which one to use.",
+				"Remember the selected org ID for the next steps."
+			].join(" "),
+			command: "CI= npx -y neonctl orgs list --output json"
+		}, {
+			id: "select_or_create_project",
+			description: [
+				"List existing Neon projects in the selected organization using the CLI command below (replace <org-id> with the selected org ID).",
+				"IMPORTANT: Preview features require a project in the AWS us-east-2 region created on or after 2026-06-11.",
+				"Filter the project list to ONLY show projects where region_id is 'aws-us-east-2' AND created_at is on or after '2026-06-11'.",
+				"If eligible projects exist, present them alongside a 'Create new project' option.",
+				"If no eligible projects exist, tell the user and proceed directly to creating a new one.",
+				"IMPORTANT: Always include --org-id when creating a project to avoid interactive prompts."
+			].join(" "),
+			command: "CI= npx -y neonctl projects list --org-id <org-id> --output json"
+		}, {
+			id: "create_project_if_needed",
+			description: [
+				"If the user chose to create a new project, create it in the AWS us-east-2 region using the CLI command below (replace <org-id> and <project-name>).",
+				"Ask the user for a project name (suggest the current directory name).",
+				"If the user chose an existing eligible project, skip this step."
+			].join(" "),
+			command: "CI= npx -y neonctl projects create --name <project-name> --org-id <org-id> --region-id aws-us-east-2 --output json"
+		});
+		else steps.push({
+			id: "select_org",
+			description: [
+				"List the user's Neon organizations using the CLI command below.",
+				"If only one org exists, use it automatically.",
+				"If multiple orgs exist, ask the user which one to use.",
+				"Remember the selected org ID for the next steps."
+			].join(" "),
+			command: "CI= npx -y neonctl orgs list --output json"
+		}, {
+			id: "select_or_create_project",
+			description: [
+				"List existing Neon projects in the selected organization using the CLI command below (replace <org-id> with the selected org ID).",
+				"Ask the user whether they want to use an existing project or create a new one.",
+				"If creating new, ask the user for a project name (suggest the current directory name).",
+				"IMPORTANT: Always include --org-id when creating a project to avoid interactive prompts."
+			].join(" "),
+			command: "CI= npx -y neonctl projects list --org-id <org-id> --output json"
+		}, {
+			id: "create_project_if_needed",
+			description: ["If the user chose to create a new project, create it using the CLI command below (replace <org-id> and <project-name>).", "If the user chose an existing project, skip this step."].join(" "),
+			command: "CI= npx -y neonctl projects create --name <project-name> --org-id <org-id> --output json"
+		});
+		steps.push({
+			id: "create_neon_context",
+			description: [
+				"Update the .neon context file in the project root with the selected org and project IDs.",
+				"IMPORTANT: If a .neon file already exists, you MUST read it first, then merge the new orgId and projectId into the existing content. Do NOT overwrite the file — other fields (like _init, branch, etc.) must be preserved.",
+				"If no .neon file exists, create one.",
+				"The file is JSON. Add/update only the orgId and projectId fields: {\"orgId\": \"<org-id>\", \"projectId\": \"<project-id>\", ...existing fields}.",
+				"This file is safe to commit — it contains no secrets."
+			].join(" ")
+		});
+		steps.push({
+			id: "install_dependencies",
+			description: [
+				"Check if node_modules exists in the project root.",
+				"If not, install project dependencies using the appropriate package manager (check for pnpm-lock.yaml, yarn.lock, bun.lockb, or default to npm).",
+				"This must be done before `neonctl env pull` because the project's Neon config file may import packages that need to be installed first."
+			].join(" "),
+			command: "npm install"
+		});
+		steps.push({
+			id: "pull_env",
+			description: [
+				"Now that the .neon context file is in place and dependencies are installed, run `neonctl env pull` to populate the project's environment variables.",
+				"This automatically writes the database connection string (and any other Neon-managed env vars) to the correct env file.",
+				"It reads the .neon context file to determine the project, and writes to the appropriate env file for the project.",
+				"Ensure the target env file is listed in .gitignore."
+			].join(" "),
+			command: "CI= npx -y neonctl env pull"
+		});
+		if (options.orm === "prisma") steps.push({
+			id: "install_driver",
+			description: ["Install the @neondatabase/serverless driver adapter for Prisma.", "This enables Prisma to use Neon's serverless driver for edge/serverless deployments."].join(" "),
+			command: "npm install @neondatabase/serverless @prisma/adapter-neon"
+		});
+		else if (options.orm === "drizzle" || options.orm === "drizzle-orm") steps.push({
+			id: "install_driver",
+			description: "Install the Neon serverless driver for Drizzle.",
+			command: "npm install @neondatabase/serverless"
+		});
+		else if (!options.orm || options.orm === "none") steps.push({
+			id: "install_driver",
+			description: "Install the Neon serverless driver for direct database access.",
+			command: "npm install @neondatabase/serverless"
+		});
+	}
+	if (options.migrationTool && options.migrationTool !== "none") {
+		const tool = options.migrationTool.toLowerCase();
+		const migrationDir = options.migrationDir;
+		const hasMigrationDir = migrationDir && migrationDir !== "none";
+		if (tool === "drizzle") steps.push({
+			id: "run_migrations",
+			description: [
+				hasMigrationDir ? `Check if the ${migrationDir} directory contains .sql migration files.` : "Check if a drizzle migrations directory exists with .sql files.",
+				"If .sql files exist, apply them with `npx drizzle-kit migrate`.",
+				"If the directory is empty or missing but a drizzle schema file exists (e.g. src/db/schema.ts, drizzle/schema.ts), run `npx drizzle-kit generate` first to create migrations, then `npx drizzle-kit migrate` to apply them.",
+				"If neither schema nor migrations exist, skip this step."
+			].join(" "),
+			command: "npx drizzle-kit migrate"
+		});
+		else if (tool === "prisma") steps.push({
+			id: "run_migrations",
+			description: [
+				hasMigrationDir ? `Check if the ${migrationDir} directory contains migration folders.` : "Check if prisma/migrations contains migration folders.",
+				"If migrations exist, apply them with `npx prisma migrate deploy`.",
+				"If the migrations directory is empty or missing but prisma/schema.prisma has models defined, run `npx prisma migrate dev --name init` to create and apply the initial migration.",
+				"If no models are defined, skip this step."
+			].join(" "),
+			command: "npx prisma migrate deploy"
+		});
+		else if (tool === "knex") steps.push({
+			id: "run_migrations",
+			description: `Apply existing knex migrations to the Neon database.`,
+			command: "npx knex migrate:latest"
+		});
+	} else if (options.preview) steps.push({
+		id: "run_migrations",
+		description: [
+			"Check the scaffolded project for a migration tool and schema.",
+			"Look for: drizzle.config.ts/js (Drizzle), prisma/schema.prisma (Prisma), or knexfile.ts/js (Knex).",
+			"If Drizzle is found: check if a drizzle migrations directory exists with .sql files. If .sql files exist, run `npx drizzle-kit migrate`. If the directory is empty or missing but a schema file exists, run `npx drizzle-kit generate` first, then `npx drizzle-kit migrate`.",
+			"If Prisma is found: check if prisma/migrations contains migration folders. If yes, run `npx prisma migrate deploy`. If not but models exist, run `npx prisma migrate dev --name init`.",
+			"If no migration tool is found, skip this step."
+		].join(" ")
+	});
+	steps.push({
+		id: "verify_connection",
+		description: [
+			"Verify the database connection works by running a SQL query against the Neon database.",
+			"Write and run a short script that connects using DATABASE_URL from the project's env file and executes `SELECT 1` (or queries a table from the migration if migrations were run).",
+			"Do NOT use the neonctl CLI or MCP tools for this — use a direct database connection to verify end-to-end connectivity."
+		].join(" ")
+	});
+	return {
+		phase: "setup",
+		status: "getting_started",
+		nextAction: {
+			type: "agent_action",
+			prerequisite: SKILL_REFERENCE_URLS.gettingStarted,
+			steps,
+			onComplete: buildOnComplete(options)
+		}
+	};
+}
+function buildOnComplete(options) {
+	const agentArgs = options.agent ? ["--agent", options.agent] : [];
+	const features = options.features ?? [];
+	const hasFeatureRequirements = features.length > 0;
+	if (hasFeatureRequirements && !features.includes("auth")) return {
+		type: "run_neon_init",
+		args: [
+			"finalize",
+			"--json",
+			...agentArgs
+		]
+	};
+	const authSetup = hasFeatureRequirements && features.includes("auth") ? ["--setup"] : [];
+	return {
+		type: "run_neon_init",
+		args: [
+			"neon-auth",
+			"--json",
+			...agentArgs,
+			...authSetup
+		]
+	};
+}
+//#endregion
+export { handleGettingStartedPhase };
+
+//# sourceMappingURL=getting-started.js.map

package/dist/lib/phases/getting-started.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getting-started.js","names":[],"sources":["../../../src/lib/phases/getting-started.ts"],"sourcesContent":["import { ensureSkillsUpToDate, SKILL_REFERENCE_URLS } from \"../skills.js\";\nimport type { PhaseResponse } from \"../types.js\";\n\nexport interface GettingStartedPhaseOptions {\n\tagent?: string;\n\thasConnectionString?: boolean;\n\tframework?: string;\n\torm?: string;\n\tmigrationTool?: string;\n\tmigrationDir?: string;\n\t/** Neon features required by the project (from .neon or template) */\n\tfeatures?: string[];\n\t/** Preview mode — restricts project creation to new projects in AWS us-east */\n\tpreview?: boolean;\n}\n\n/**\n * Initiates the \"Get started with Neon\" workflow.\n *\n * Steps are concrete and executable — each has a CLI command to run\n * or a specific file operation. The agent should attempt each step\n * in order and actually perform the action using the neonctl CLI.\n */\nexport async function handleGettingStartedPhase(\n\toptions: GettingStartedPhaseOptions,\n): Promise<PhaseResponse> {\n\t// Ensure skills are up to date (no-op if recently updated)\n\tif (options.agent) {\n\t\tawait ensureSkillsUpToDate(options.agent);\n\t}\n\tconst steps: { id: string; description: string; command?: string }[] = [];\n\n\tif (!options.hasConnectionString) {\n\t\tif (options.preview) {\n\t\t\t// Preview mode: new project in AWS us-east-2, or existing eligible project\n\t\t\tsteps.push(\n\t\t\t\t{\n\t\t\t\t\tid: \"select_org\",\n\t\t\t\t\tdescription: [\n\t\t\t\t\t\t\"List the user's Neon organizations using the CLI command below.\",\n\t\t\t\t\t\t\"If only one org exists, use it automatically.\",\n\t\t\t\t\t\t\"If multiple orgs exist, ask the user which one to use.\",\n\t\t\t\t\t\t\"Remember the selected org ID for the next steps.\",\n\t\t\t\t\t].join(\" \"),\n\t\t\t\t\tcommand: \"CI= npx -y neonctl orgs list --output json\",\n\t\t\t\t},\n\t\t\t\t{\n\t\t\t\t\tid: \"select_or_create_project\",\n\t\t\t\t\tdescription: [\n\t\t\t\t\t\t\"List existing Neon projects in the selected organization using the CLI command below (replace <org-id> with the selected org ID).\",\n\t\t\t\t\t\t\"IMPORTANT: Preview features require a project in the AWS us-east-2 region created on or after 2026-06-11.\",\n\t\t\t\t\t\t\"Filter the project list to ONLY show projects where region_id is 'aws-us-east-2' AND created_at is on or after '2026-06-11'.\",\n\t\t\t\t\t\t\"If eligible projects exist, present them alongside a 'Create new project' option.\",\n\t\t\t\t\t\t\"If no eligible projects exist, tell the user and proceed directly to creating a new one.\",\n\t\t\t\t\t\t\"IMPORTANT: Always include --org-id when creating a project to avoid interactive prompts.\",\n\t\t\t\t\t].join(\" \"),\n\t\t\t\t\tcommand:\n\t\t\t\t\t\t\"CI= npx -y neonctl projects list --org-id <org-id> --output json\",\n\t\t\t\t},\n\t\t\t\t{\n\t\t\t\t\tid: \"create_project_if_needed\",\n\t\t\t\t\tdescription: [\n\t\t\t\t\t\t\"If the user chose to create a new project, create it in the AWS us-east-2 region using the CLI command below (replace <org-id> and <project-name>).\",\n\t\t\t\t\t\t\"Ask the user for a project name (suggest the current directory name).\",\n\t\t\t\t\t\t\"If the user chose an existing eligible project, skip this step.\",\n\t\t\t\t\t].join(\" \"),\n\t\t\t\t\tcommand:\n\t\t\t\t\t\t\"CI= npx -y neonctl projects create --name <project-name> --org-id <org-id> --region-id aws-us-east-2 --output json\",\n\t\t\t\t},\n\t\t\t);\n\t\t} else {\n\t\t\t// Standard mode: let user choose existing or create new\n\t\t\tsteps.push(\n\t\t\t\t{\n\t\t\t\t\tid: \"select_org\",\n\t\t\t\t\tdescription: [\n\t\t\t\t\t\t\"List the user's Neon organizations using the CLI command below.\",\n\t\t\t\t\t\t\"If only one org exists, use it automatically.\",\n\t\t\t\t\t\t\"If multiple orgs exist, ask the user which one to use.\",\n\t\t\t\t\t\t\"Remember the selected org ID for the next steps.\",\n\t\t\t\t\t].join(\" \"),\n\t\t\t\t\tcommand: \"CI= npx -y neonctl orgs list --output json\",\n\t\t\t\t},\n\t\t\t\t{\n\t\t\t\t\tid: \"select_or_create_project\",\n\t\t\t\t\tdescription: [\n\t\t\t\t\t\t\"List existing Neon projects in the selected organization using the CLI command below (replace <org-id> with the selected org ID).\",\n\t\t\t\t\t\t\"Ask the user whether they want to use an existing project or create a new one.\",\n\t\t\t\t\t\t\"If creating new, ask the user for a project name (suggest the current directory name).\",\n\t\t\t\t\t\t\"IMPORTANT: Always include --org-id when creating a project to avoid interactive prompts.\",\n\t\t\t\t\t].join(\" \"),\n\t\t\t\t\tcommand:\n\t\t\t\t\t\t\"CI= npx -y neonctl projects list --org-id <org-id> --output json\",\n\t\t\t\t},\n\t\t\t\t{\n\t\t\t\t\tid: \"create_project_if_needed\",\n\t\t\t\t\tdescription: [\n\t\t\t\t\t\t\"If the user chose to create a new project, create it using the CLI command below (replace <org-id> and <project-name>).\",\n\t\t\t\t\t\t\"If the user chose an existing project, skip this step.\",\n\t\t\t\t\t].join(\" \"),\n\t\t\t\t\tcommand:\n\t\t\t\t\t\t\"CI= npx -y neonctl projects create --name <project-name> --org-id <org-id> --output json\",\n\t\t\t\t},\n\t\t\t);\n\t\t}\n\n\t\t// Create/update .neon context file\n\t\tsteps.push({\n\t\t\tid: \"create_neon_context\",\n\t\t\tdescription: [\n\t\t\t\t\"Update the .neon context file in the project root with the selected org and project IDs.\",\n\t\t\t\t\"IMPORTANT: If a .neon file already exists, you MUST read it first, then merge the new orgId and projectId into the existing content. Do NOT overwrite the file — other fields (like _init, branch, etc.) must be preserved.\",\n\t\t\t\t\"If no .neon file exists, create one.\",\n\t\t\t\t'The file is JSON. Add/update only the orgId and projectId fields: {\"orgId\": \"<org-id>\", \"projectId\": \"<project-id>\", ...existing fields}.',\n\t\t\t\t\"This file is safe to commit — it contains no secrets.\",\n\t\t\t].join(\" \"),\n\t\t});\n\n\t\t// Install project dependencies (required before env pull — config files may import packages)\n\t\tsteps.push({\n\t\t\tid: \"install_dependencies\",\n\t\t\tdescription: [\n\t\t\t\t\"Check if node_modules exists in the project root.\",\n\t\t\t\t\"If not, install project dependencies using the appropriate package manager (check for pnpm-lock.yaml, yarn.lock, bun.lockb, or default to npm).\",\n\t\t\t\t\"This must be done before `neonctl env pull` because the project's Neon config file may import packages that need to be installed first.\",\n\t\t\t].join(\" \"),\n\t\t\tcommand: \"npm install\",\n\t\t});\n\n\t\t// Pull environment variables (connection string, etc.) from Neon\n\t\tsteps.push({\n\t\t\tid: \"pull_env\",\n\t\t\tdescription: [\n\t\t\t\t\"Now that the .neon context file is in place and dependencies are installed, run `neonctl env pull` to populate the project's environment variables.\",\n\t\t\t\t\"This automatically writes the database connection string (and any other Neon-managed env vars) to the correct env file.\",\n\t\t\t\t\"It reads the .neon context file to determine the project, and writes to the appropriate env file for the project.\",\n\t\t\t\t\"Ensure the target env file is listed in .gitignore.\",\n\t\t\t].join(\" \"),\n\t\t\tcommand: \"CI= npx -y neonctl env pull\",\n\t\t});\n\n\t\t// Step 6: Install Neon serverless driver if needed\n\t\tif (options.orm === \"prisma\") {\n\t\t\tsteps.push({\n\t\t\t\tid: \"install_driver\",\n\t\t\t\tdescription: [\n\t\t\t\t\t\"Install the @neondatabase/serverless driver adapter for Prisma.\",\n\t\t\t\t\t\"This enables Prisma to use Neon's serverless driver for edge/serverless deployments.\",\n\t\t\t\t].join(\" \"),\n\t\t\t\tcommand:\n\t\t\t\t\t\"npm install @neondatabase/serverless @prisma/adapter-neon\",\n\t\t\t});\n\t\t} else if (options.orm === \"drizzle\" || options.orm === \"drizzle-orm\") {\n\t\t\tsteps.push({\n\t\t\t\tid: \"install_driver\",\n\t\t\t\tdescription: \"Install the Neon serverless driver for Drizzle.\",\n\t\t\t\tcommand: \"npm install @neondatabase/serverless\",\n\t\t\t});\n\t\t} else if (!options.orm || options.orm === \"none\") {\n\t\t\tsteps.push({\n\t\t\t\tid: \"install_driver\",\n\t\t\t\tdescription:\n\t\t\t\t\t\"Install the Neon serverless driver for direct database access.\",\n\t\t\t\tcommand: \"npm install @neondatabase/serverless\",\n\t\t\t});\n\t\t}\n\t}\n\n\t// Run migrations if applicable\n\tif (options.migrationTool && options.migrationTool !== \"none\") {\n\t\tconst tool = options.migrationTool.toLowerCase();\n\t\tconst migrationDir = options.migrationDir;\n\t\tconst hasMigrationDir = migrationDir && migrationDir !== \"none\";\n\n\t\tif (tool === \"drizzle\") {\n\t\t\tsteps.push({\n\t\t\t\tid: \"run_migrations\",\n\t\t\t\tdescription: [\n\t\t\t\t\thasMigrationDir\n\t\t\t\t\t\t? `Check if the ${migrationDir} directory contains .sql migration files.`\n\t\t\t\t\t\t: \"Check if a drizzle migrations directory exists with .sql files.\",\n\t\t\t\t\t\"If .sql files exist, apply them with `npx drizzle-kit migrate`.\",\n\t\t\t\t\t\"If the directory is empty or missing but a drizzle schema file exists (e.g. src/db/schema.ts, drizzle/schema.ts), run `npx drizzle-kit generate` first to create migrations, then `npx drizzle-kit migrate` to apply them.\",\n\t\t\t\t\t\"If neither schema nor migrations exist, skip this step.\",\n\t\t\t\t].join(\" \"),\n\t\t\t\tcommand: \"npx drizzle-kit migrate\",\n\t\t\t});\n\t\t} else if (tool === \"prisma\") {\n\t\t\tsteps.push({\n\t\t\t\tid: \"run_migrations\",\n\t\t\t\tdescription: [\n\t\t\t\t\thasMigrationDir\n\t\t\t\t\t\t? `Check if the ${migrationDir} directory contains migration folders.`\n\t\t\t\t\t\t: \"Check if prisma/migrations contains migration folders.\",\n\t\t\t\t\t\"If migrations exist, apply them with `npx prisma migrate deploy`.\",\n\t\t\t\t\t\"If the migrations directory is empty or missing but prisma/schema.prisma has models defined, run `npx prisma migrate dev --name init` to create and apply the initial migration.\",\n\t\t\t\t\t\"If no models are defined, skip this step.\",\n\t\t\t\t].join(\" \"),\n\t\t\t\tcommand: \"npx prisma migrate deploy\",\n\t\t\t});\n\t\t} else if (tool === \"knex\") {\n\t\t\tsteps.push({\n\t\t\t\tid: \"run_migrations\",\n\t\t\t\tdescription: `Apply existing knex migrations to the Neon database.`,\n\t\t\t\tcommand: \"npx knex migrate:latest\",\n\t\t\t});\n\t\t}\n\t} else if (options.preview) {\n\t\t// Bootstrap flow: migration tool wasn't detected because the project was\n\t\t// inspected before scaffolding. Detect and run migrations from the scaffolded template.\n\t\tsteps.push({\n\t\t\tid: \"run_migrations\",\n\t\t\tdescription: [\n\t\t\t\t\"Check the scaffolded project for a migration tool and schema.\",\n\t\t\t\t\"Look for: drizzle.config.ts/js (Drizzle), prisma/schema.prisma (Prisma), or knexfile.ts/js (Knex).\",\n\t\t\t\t\"If Drizzle is found: check if a drizzle migrations directory exists with .sql files. If .sql files exist, run `npx drizzle-kit migrate`. If the directory is empty or missing but a schema file exists, run `npx drizzle-kit generate` first, then `npx drizzle-kit migrate`.\",\n\t\t\t\t\"If Prisma is found: check if prisma/migrations contains migration folders. If yes, run `npx prisma migrate deploy`. If not but models exist, run `npx prisma migrate dev --name init`.\",\n\t\t\t\t\"If no migration tool is found, skip this step.\",\n\t\t\t].join(\" \"),\n\t\t});\n\t}\n\n\t// Verify the connection\n\tsteps.push({\n\t\tid: \"verify_connection\",\n\t\tdescription: [\n\t\t\t\"Verify the database connection works by running a SQL query against the Neon database.\",\n\t\t\t\"Write and run a short script that connects using DATABASE_URL from the project's env file and executes `SELECT 1` (or queries a table from the migration if migrations were run).\",\n\t\t\t\"Do NOT use the neonctl CLI or MCP tools for this — use a direct database connection to verify end-to-end connectivity.\",\n\t\t].join(\" \"),\n\t});\n\n\treturn {\n\t\tphase: \"setup\",\n\t\tstatus: \"getting_started\",\n\t\tnextAction: {\n\t\t\ttype: \"agent_action\",\n\t\t\tprerequisite: SKILL_REFERENCE_URLS.gettingStarted,\n\t\t\tsteps,\n\t\t\tonComplete: buildOnComplete(options),\n\t\t},\n\t};\n}\n\nfunction buildOnComplete(\n\toptions: GettingStartedPhaseOptions,\n): import(\"../types.js\").RunNeonInitAction {\n\tconst agentArgs = options.agent ? [\"--agent\", options.agent] : [];\n\tconst features = options.features ?? [];\n\tconst hasFeatureRequirements = features.length > 0;\n\n\t// If features are specified and auth is not required, go to finalize\n\tif (hasFeatureRequirements && !features.includes(\"auth\")) {\n\t\treturn {\n\t\t\ttype: \"run_neon_init\",\n\t\t\targs: [\"finalize\", \"--json\", ...agentArgs],\n\t\t};\n\t}\n\n\t// Chain to neon-auth — if user already selected auth via features, go straight to setup\n\tconst authSetup =\n\t\thasFeatureRequirements && features.includes(\"auth\") ? [\"--setup\"] : [];\n\treturn {\n\t\ttype: \"run_neon_init\",\n\t\targs: [\"neon-auth\", \"--json\", ...agentArgs, ...authSetup],\n\t};\n}\n"],"mappings":"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"}

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

@@ -0,0 +1,15 @@
+import { Editor, PhaseResponse } from "../types.js";
+
+//#region src/lib/phases/mcp.d.ts
+interface McpPhaseOptions {
+  agent?: string;
+  editor?: Editor;
+  status?: boolean;
+  install?: boolean;
+  scope?: "global" | "project";
+  mcpConfigured?: boolean | null;
+}
+declare function handleMcpPhase(options: McpPhaseOptions): Promise<PhaseResponse>;
+//#endregion
+export { McpPhaseOptions, handleMcpPhase };
+//# sourceMappingURL=mcp.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","names":[],"sources":["../../../src/lib/phases/mcp.ts"],"mappings":";;;UAIiB,eAAA;;EAAA,MAAA,CAAA,EAEP,MAFO;EASK,MAAA,CAAA,EAAA,OAAA;EAAc,OAAA,CAAA,EAAA,OAAA;OAC1B,CAAA,EAAA,QAAA,GAAA,SAAA;eACC,CAAA,EAAA,OAAA,GAAA,IAAA;;AAAD,iBAFY,cAAA,CAEZ,OAAA,EADA,eACA,CAAA,EAAP,OAAO,CAAC,aAAD,CAAA"}