neon 2.45.0 → 2.46.0

package/dist/init/neonctl.js

@@ -0,0 +1,184 @@
+import { lstatSync } from "node:fs";
+import { execa } from "execa";
+/**
+ * Returns the Neon CLI command prefix: "CI= npx -y neon".
+ *
+ * The CLI reads NEON_API_HOST and NEON_OAUTH_HOST from the environment
+ * directly, so no extra flags are needed. The `neon` package ships both the
+ * `neon` and `neonctl` binaries; we surface the cleaner `neon` command in the
+ * examples emitted to users and agents.
+ *
+ * Usage: `${neonctlCmd()} orgs list --output json`
+ */
+export function neonctlCmd() {
+    return "CI= npx -y neon";
+}
+/**
+ * Detects which package manager was used to invoke the current process.
+ * Reads the `npm_config_user_agent` env var set by npm/pnpm/yarn/bun when
+ * they spawn child processes (including via `npx`, `pnpx`, `bunx`, etc.).
+ *
+ * Falls back to "npm" if detection fails.
+ */
+export function detectPackageManager() {
+    const ua = process.env.npm_config_user_agent;
+    if (ua) {
+        if (ua.startsWith("pnpm/"))
+            return "pnpm";
+        if (ua.startsWith("yarn/"))
+            return "yarn";
+        if (ua.startsWith("bun/"))
+            return "bun";
+    }
+    return "npm";
+}
+/**
+ * Returns the global install command for a given package manager.
+ */
+function globalInstallArgs(pm, pkg) {
+    switch (pm) {
+        case "pnpm":
+            return { command: "pnpm", args: ["add", "-g", pkg] };
+        case "yarn":
+            return { command: "yarn", args: ["global", "add", pkg] };
+        case "bun":
+            return { command: "bun", args: ["add", "-g", pkg] };
+        default:
+            return { command: "npm", args: ["install", "-g", pkg] };
+    }
+}
+/**
+ * Gets the currently available neonctl version.
+ * Tries the global binary first, then falls back to npx.
+ */
+async function getNeonctlVersion() {
+    // Try global binary first (fast path)
+    try {
+        const result = await execa("neonctl", ["--version"], {
+            stdio: "pipe",
+            timeout: 5000,
+        });
+        const match = result.stdout.trim().match(/(\d+\.\d+\.\d+)/);
+        if (match)
+            return match[1];
+    }
+    catch {
+        // Not globally installed — that's fine
+    }
+    return null;
+}
+/**
+ * Checks whether the neonctl CLI is globally installed and whether it's up to date.
+ */
+export async function checkNeonctl() {
+    const currentVersion = await getNeonctlVersion();
+    if (!currentVersion) {
+        return {
+            installed: false,
+            currentVersion: null,
+            latestVersion: null,
+            needsUpdate: true,
+        };
+    }
+    // Check latest version from npm registry
+    let latestVersion = null;
+    try {
+        const result = await execa("npm", ["view", "neonctl", "version"], {
+            stdio: "pipe",
+            timeout: 10000,
+        });
+        latestVersion = result.stdout.trim();
+    }
+    catch {
+        // Can't determine latest — assume current is fine
+        return {
+            installed: true,
+            currentVersion,
+            latestVersion: null,
+            needsUpdate: false,
+        };
+    }
+    const needsUpdate = currentVersion !== null &&
+        latestVersion !== null &&
+        currentVersion !== latestVersion &&
+        isOlderVersion(currentVersion, latestVersion);
+    return { installed: true, currentVersion, latestVersion, needsUpdate };
+}
+function isOlderVersion(current, latest) {
+    const c = current.split(".").map(Number);
+    const l = latest.split(".").map(Number);
+    for (let i = 0; i < 3; i++) {
+        if ((c[i] ?? 0) < (l[i] ?? 0))
+            return true;
+        if ((c[i] ?? 0) > (l[i] ?? 0))
+            return false;
+    }
+    return false;
+}
+/**
+ * Checks if neonctl is installed via a local dev symlink.
+ * If so, skip install/update — the developer manages it manually.
+ */
+function isLocalDevSymlink() {
+    try {
+        const home = process.env.HOME || process.env.USERPROFILE || "";
+        const nvmDir = process.env.NVM_DIR || `${home}/.nvm`;
+        // Check common global module locations for a symlink
+        const candidates = [
+            `${nvmDir}/versions/node/${process.version}/lib/node_modules/neonctl`,
+            `${home}/.nvm/versions/node/${process.version}/lib/node_modules/neonctl`,
+        ];
+        for (const candidate of candidates) {
+            try {
+                const stat = lstatSync(candidate);
+                if (stat.isSymbolicLink())
+                    return true;
+            }
+            catch {
+                // path doesn't exist
+            }
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Ensures neonctl is globally installed and up to date.
+ * Uses the same package manager that invoked the init command.
+ */
+export async function ensureNeonctl() {
+    // Skip install for local dev symlinks to avoid permission errors
+    if (isLocalDevSymlink()) {
+        const version = await getNeonctlVersion();
+        return {
+            status: "already_current",
+            version: version ?? "dev",
+        };
+    }
+    const check = await checkNeonctl();
+    if (check.installed && !check.needsUpdate) {
+        return {
+            status: "already_current",
+            version: check.currentVersion ?? undefined,
+        };
+    }
+    const pm = detectPackageManager();
+    const { command, args } = globalInstallArgs(pm, "neonctl");
+    try {
+        await execa(command, args, { stdio: "pipe", timeout: 60000 });
+        // Verify installation
+        const version = await getNeonctlVersion();
+        return {
+            status: check.installed ? "updated" : "installed",
+            version: version ?? undefined,
+        };
+    }
+    catch (err) {
+        return {
+            status: "failed",
+            error: err instanceof Error ? err.message : "Unknown error",
+        };
+    }
+}

package/dist/init/orchestrate.js

@@ -0,0 +1,190 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { isAuthenticated } from "./auth.js";
+import { inspectProject } from "./inspect.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";
+/**
+ * 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
+ */
+export async function orchestrate(options) {
+    // Phase 1: Auth
+    const authed = await isAuthenticated();
+    if (!authed) {
+        return handleAuthPhase({ agent: options.agent });
+    }
+    const cwd = process.cwd();
+    // Phase 2: Inspect what's already in place
+    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: [] },
+    ]);
+    // Only detect empty projects when --preview is enabled
+    const hasApp = options.preview ? inspection.hasApp === true : true;
+    // When preview is enabled, check that all preview skills are installed too
+    let skillsInstalled = inspection.skillsInstalled;
+    if (options.preview && skillsInstalled && inspection.skillsScope) {
+        const { getSkillList } = await import("./skills.js");
+        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 scope = inspection.skillsScope;
+        const dirs = scope === "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"),
+            ];
+        const allPresent = previewSkills.every((skill) => dirs.some((dir) => exists(resolvePath(dir, skill, "SKILL.md"))));
+        if (!allPresent) {
+            skillsInstalled = false;
+            // Mark as partial so setup auto-completes to the same scope
+            inspection.skillsScope =
+                `${inspection.skillsScope}-partial`;
+        }
+    }
+    const toolingInstalled = inspection.mcpConfigured && skillsInstalled;
+    const hasNeonConnection = inspection.connectionString === true;
+    // Phase 3a: No app or tooling not installed → setup flow
+    // When !hasApp (preview mode), setup will offer template selection before asking about tooling.
+    // Clean up any stale _init state from a previous run.
+    if (!hasApp || !toolingInstalled) {
+        cleanupInitState(resolve(cwd, ".neon"));
+        return handleSetupPhase({
+            agent: options.agent,
+            preview: options.preview,
+            hasApp,
+            mcpConfigured: inspection.mcpConfigured ?? null,
+            mcpScope: inspection.mcpScope || undefined,
+            skillsInstalled: skillsInstalled ?? null,
+            skillsScope: inspection.skillsScope || undefined,
+        });
+    }
+    // Read .neon context early — needed for feature-based routing
+    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
+        : [];
+    // Phase 3b: Tooling installed but no Neon connection string → getting-started
+    if (!hasNeonConnection) {
+        return handleGettingStartedPhase({
+            agent: options.agent,
+            hasConnectionString: false,
+            framework: inspection.framework,
+            orm: inspection.orm,
+            migrationTool: inspection.migrationTool,
+            migrationDir: inspection.migrationDir,
+            features,
+            preview: options.preview,
+        });
+    }
+    // Phase 3c: Neon connection exists but no .neon context file → resolve project
+    if (!neonContext.projectId) {
+        // Resolve the project from the connection string and merge into .neon
+        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 {
+            // Continue the flow regardless — missing .neon is not a blocker
+        }
+    }
+    // Phase 4: Neon Auth — only if features include "auth"
+    if (features.includes("auth")) {
+        const hasNeonAuth = checkNeonAuth(cwd);
+        if (!hasNeonAuth) {
+            return handleNeonAuthPhase({
+                agent: options.agent,
+                setup: true,
+            });
+        }
+    }
+    // Phase 5: Migrations
+    if (!options.skipMigrations) {
+        return handleMigrationsPhase({ agent: options.agent });
+    }
+    // All done — clean up ephemeral _init state from .neon
+    cleanupInitState(neonContextPath);
+    return {
+        phase: "setup",
+        status: "complete",
+        nextAction: {
+            type: "complete",
+            message: "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 !== undefined) {
+            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;
+    }
+}

package/dist/init/phases/auth.js

@@ -0,0 +1,209 @@
+import { isAuthenticated } from "../auth.js";
+import { neonctlCmd } from "../neonctl.js";
+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}`,
+    };
+}
+export async function handleAuthPhase(options) {
+    const agentArgs = options.agent
+        ? ["--agent", options.agent, "--json"]
+        : ["--json"];
+    // --verify: just check if credentials exist
+    if (options.verify) {
+        const authed = await isAuthenticated();
+        if (authed) {
+            // Continue the flow immediately — don't use "complete" which
+            // causes agents to stop and get distracted by neonctl output.
+            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"],
+            },
+        };
+    }
+    // Check if already authenticated
+    const authed = await isAuthenticated();
+    if (authed) {
+        return {
+            phase: "auth",
+            status: "verified",
+            nextAction: {
+                type: "run_neon_init",
+                args: agentArgs,
+            },
+        };
+    }
+    // --method new: guide through signup
+    if (options.method === "new") {
+        const openCmd = getSignupCommands()[process.platform] ?? getSignupCommands().linux;
+        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: 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"],
+                },
+            },
+        };
+    }
+    // --method existing: run OAuth flow
+    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: 120000,
+                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"],
+                    },
+                },
+            },
+        };
+    }
+    // No method specified: ask the user, then launch OAuth directly for
+    // "existing account" without an intermediate CLI round-trip.
+    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: 120000,
+                        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"],
+                        },
+                    },
+                },
+            },
+        },
+    };
+}

package/dist/init/phases/cleanup.js

@@ -0,0 +1,27 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+/**
+ * Terminal phase: cleans up ephemeral _init state from .neon and
+ * returns a complete message. All feature chains should end here.
+ */
+export function handleCleanup() {
+    const neonContextPath = resolve(process.cwd(), ".neon");
+    if (existsSync(neonContextPath)) {
+        try {
+            const context = JSON.parse(readFileSync(neonContextPath, "utf-8"));
+            if (context._init !== undefined) {
+                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.",
+        },
+    };
+}