neon 2.45.0 → 2.46.0

package/dist/init/phases/skills.js

@@ -0,0 +1,89 @@
+import { getSkillsAgentName } from "../agents.js";
+import { SKILL_REFERENCE_URLS } from "../skills.js";
+export async function handleSkillsPhase(options) {
+    const agentArgs = options.agent
+        ? ["--agent", options.agent, "--json"]
+        : ["--json"];
+    const skillsAgent = options.agent
+        ? getSkillsAgentName(options.agent)
+        : "claude-code";
+    // --status: ask agent to check
+    if (options.status) {
+        return {
+            phase: "tooling",
+            status: "skills_check",
+            nextAction: {
+                type: "agent_check",
+                checks: [
+                    {
+                        id: "skills",
+                        description: "Check if Neon agent skills are installed in this project",
+                        lookFor: [
+                            "A skill file referencing 'neon-postgres' (e.g. .cursor/skills/, CLAUDE.md, .cursorrules)",
+                            "A .skills/ directory with neon-related content",
+                        ],
+                    },
+                ],
+                reportBack: {
+                    type: "run_neon_init",
+                    args: [
+                        "skills",
+                        "--json",
+                        ...(options.agent ? ["--agent", options.agent] : []),
+                        ...(options.update ? ["--update"] : ["--install"]),
+                    ],
+                },
+            },
+        };
+    }
+    // --install or --update: run the skills CLI
+    if (options.install || options.update) {
+        const installCmd = `npx -y skills add neondatabase/agent-skills --skill neon-postgres --agent ${skillsAgent} -y`;
+        return {
+            phase: "tooling",
+            status: "installing_skills",
+            nextAction: {
+                type: "run_command",
+                command: installCmd,
+                description: `Installing Neon agent skills for ${skillsAgent}.`,
+                timeout: 30000,
+                onSuccess: {
+                    type: "run_neon_init",
+                    args: agentArgs,
+                },
+                onFailure: {
+                    other: {
+                        type: "run_neon_init",
+                        args: agentArgs,
+                    },
+                },
+            },
+            skillReferences: SKILL_REFERENCE_URLS,
+        };
+    }
+    // Default: ask if they want skills installed
+    return {
+        phase: "tooling",
+        status: "skills_available",
+        nextAction: {
+            type: "ask_user",
+            question: "Would you like to install Neon agent skills for this project? Skills provide your AI assistant with Neon-specific knowledge.",
+            options: [
+                { value: "yes", label: "Yes, install skills" },
+                { value: "skip", label: "Skip for now" },
+            ],
+            context: "Agent skills include guides for connection patterns, Neon Auth setup, branching, migrations, and more.",
+            responseMapping: {
+                yes: {
+                    args: [
+                        "skills",
+                        "--json",
+                        ...(options.agent ? ["--agent", options.agent] : []),
+                        "--install",
+                    ],
+                },
+                skip: { args: agentArgs },
+            },
+        },
+    };
+}

package/dist/init/phases/status.js

@@ -0,0 +1,70 @@
+import { isAuthenticated } from "../auth.js";
+import { inspectProject } from "../inspect.js";
+export async function handleStatusPhase(_options) {
+    const authed = await isAuthenticated();
+    const inspection = await inspectProject([
+        { id: "mcp_server", description: "", lookFor: [] },
+        { id: "database_url", description: "", lookFor: [] },
+        { id: "skills", description: "", lookFor: [] },
+        { id: "migrations", description: "", lookFor: [] },
+    ]);
+    const hasDatabaseUrl = inspection.databaseUrl === true;
+    const mcpConfigured = inspection.mcpConfigured === true;
+    const skillsInstalled = inspection.skillsInstalled === true;
+    const migrationTool = inspection.migrationTool ?? null;
+    const hasMigrations = migrationTool !== null &&
+        migrationTool !== "none" &&
+        inspection.migrationDir !== "none";
+    const recommendations = [];
+    if (!authed) {
+        recommendations.push({
+            priority: "high",
+            message: "Not authenticated with Neon",
+            command: `neon init --agent --data '{"step":"auth"}'`,
+        });
+    }
+    if (!hasDatabaseUrl) {
+        recommendations.push({
+            priority: "high",
+            message: "No DATABASE_URL found in .env",
+            command: `neon init --agent --data '{"step":"db"}'`,
+        });
+    }
+    if (!skillsInstalled) {
+        recommendations.push({
+            priority: "medium",
+            message: "Neon agent skills not detected in this project",
+            command: `neon init --agent --data '{"step":"skills","install":true}'`,
+        });
+    }
+    if (migrationTool && !hasMigrations) {
+        recommendations.push({
+            priority: "medium",
+            message: `${migrationTool} detected but no migrations found`,
+            command: `neon init --agent --data '{"step":"migrations"}'`,
+        });
+    }
+    return {
+        auth: {
+            authenticated: authed,
+        },
+        tooling: {
+            mcpServer: {
+                configured: mcpConfigured,
+                scope: inspection.mcpScope || null,
+            },
+            skills: {
+                installed: skillsInstalled,
+                scope: inspection.skillsScope || null,
+            },
+        },
+        project: {
+            databaseUrl: hasDatabaseUrl,
+        },
+        migrations: {
+            tool: migrationTool,
+            hasMigrations,
+        },
+        recommendations,
+    };
+}

package/dist/init/resolve_context.js

@@ -0,0 +1,107 @@
+/**
+ * Resolves the Neon org/project from a DATABASE_URL in .env.
+ * Parses the endpoint hostname, then queries the Neon API to find
+ * which project it belongs to.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { execa } from "execa";
+/**
+ * Extracts the Neon endpoint host from .env's DATABASE_URL or PGHOST.
+ * Returns the hostname (e.g. "ep-cool-name-12345.us-east-2.aws.neon.tech") or null.
+ */
+function extractNeonHost(cwd) {
+    for (const envFile of [".env", ".env.local"]) {
+        const envPath = resolve(cwd, envFile);
+        if (!existsSync(envPath))
+            continue;
+        try {
+            const content = readFileSync(envPath, "utf-8");
+            // Try DATABASE_URL
+            const dbUrlMatch = content.match(/^DATABASE_URL=.*@([^/:\s]+\.neon\.tech)/m);
+            if (dbUrlMatch)
+                return dbUrlMatch[1];
+            // Try PGHOST
+            const pgHostMatch = content.match(/^PGHOST=([^\s]+\.neon\.tech)/m);
+            if (pgHostMatch)
+                return pgHostMatch[1];
+        }
+        catch { }
+    }
+    return null;
+}
+/**
+ * Resolves the Neon org and project that own the endpoint in DATABASE_URL.
+ *
+ * Strategy:
+ * 1. Extract endpoint hostname from .env
+ * 2. List orgs via neonctl
+ * 3. For each org, list projects
+ * 4. For each project, get connection string and compare hostnames
+ * 5. Return the matching org/project
+ */
+export async function resolveNeonContext(cwd) {
+    const neonHost = extractNeonHost(cwd);
+    if (!neonHost)
+        return null;
+    // List orgs
+    let orgs;
+    try {
+        const result = await execa("npx", ["-y", "neonctl", "orgs", "list", "--output", "json"], {
+            stdio: "pipe",
+            timeout: 30000,
+            env: { ...process.env, CI: undefined },
+        });
+        orgs = JSON.parse(result.stdout);
+    }
+    catch {
+        return null;
+    }
+    if (orgs.length === 0)
+        return null;
+    // Search each org's projects for a matching endpoint
+    for (const org of orgs) {
+        let projects;
+        try {
+            const result = await execa("npx", [
+                "-y",
+                "neonctl",
+                "projects",
+                "list",
+                "--org-id",
+                org.id,
+                "--output",
+                "json",
+            ], {
+                stdio: "pipe",
+                timeout: 30000,
+                env: { ...process.env, CI: undefined },
+            });
+            projects = JSON.parse(result.stdout);
+        }
+        catch {
+            continue;
+        }
+        for (const project of projects) {
+            try {
+                const result = await execa("npx", [
+                    "-y",
+                    "neonctl",
+                    "connection-string",
+                    "--project-id",
+                    project.id,
+                ], {
+                    stdio: "pipe",
+                    timeout: 15000,
+                    env: { ...process.env, CI: undefined },
+                });
+                const connStr = result.stdout.trim();
+                if (connStr.includes(neonHost)) {
+                    return { orgId: org.id, projectId: project.id };
+                }
+            }
+            catch { }
+        }
+    }
+    return null;
+}

package/dist/init/route_command.js

@@ -0,0 +1,100 @@
+/**
+ * Routes a `--data` payload to a phase handler by its `step` field, without
+ * shelling out. This is the whole agent-facing surface of `neon init`:
+ *
+ *   neon init --agent --data '{"step":"auth"}'
+ *   neon init --agent --data '{"step":"db","projectId":"xyz"}'
+ */
+export async function routeDataStep(data, agent) {
+    const { step, agentId, ...rest } = data;
+    // Allow agentId override from data JSON, fall back to caller-provided agent
+    const resolvedAgent = typeof agentId === "string" ? agentId : agent;
+    // Agents sometimes nest the actual payload inside a "data" key:
+    //   {"step":"setup","data":{"mode":"defaults",...}}
+    // or as a JSON string:
+    //   {"step":"setup","data":"{\"mode\":\"defaults\",...}"}
+    // Unwrap it so the phase handler gets the right options.
+    if (rest.data !== undefined && Object.keys(rest).length === 1) {
+        let nested = rest.data;
+        if (typeof nested === "string") {
+            try {
+                nested = JSON.parse(nested);
+            }
+            catch {
+                // leave as-is
+            }
+        }
+        if (typeof nested === "object" && nested !== null) {
+            Object.assign(rest, nested);
+            delete rest.data;
+        }
+    }
+    switch (step) {
+        case "auth": {
+            const { handleAuthPhase } = await import("./phases/auth.js");
+            return handleAuthPhase({
+                agent: resolvedAgent,
+                ...rest,
+            });
+        }
+        case "db": {
+            const { handleDbPhase } = await import("./phases/db.js");
+            return handleDbPhase({
+                agent: resolvedAgent,
+                ...rest,
+            });
+        }
+        case "setup": {
+            const { handleSetupPhase } = await import("./phases/setup.js");
+            return handleSetupPhase({
+                agent: resolvedAgent,
+                ...rest,
+            });
+        }
+        case "getting-started": {
+            const { handleGettingStartedPhase } = await import("./phases/getting_started.js");
+            return handleGettingStartedPhase({
+                agent: resolvedAgent,
+                ...rest,
+            });
+        }
+        case "mcp": {
+            const { handleMcpPhase } = await import("./phases/mcp.js");
+            return handleMcpPhase({
+                agent: resolvedAgent,
+                ...rest,
+            });
+        }
+        case "skills": {
+            const { handleSkillsPhase } = await import("./phases/skills.js");
+            return handleSkillsPhase({
+                agent: resolvedAgent,
+                ...rest,
+            });
+        }
+        case "migrations": {
+            const { handleMigrationsPhase } = await import("./phases/migrations.js");
+            return handleMigrationsPhase({
+                agent: resolvedAgent,
+                ...rest,
+            });
+        }
+        case "neon-auth": {
+            const { handleNeonAuthPhase } = await import("./phases/neon_auth.js");
+            return handleNeonAuthPhase({
+                agent: resolvedAgent,
+                ...rest,
+            });
+        }
+        case "status": {
+            const { handleStatusPhase } = await import("./phases/status.js");
+            return handleStatusPhase({ agent: resolvedAgent });
+        }
+        case "finalize": {
+            const { handleCleanup } = await import("./phases/cleanup.js");
+            return handleCleanup();
+        }
+        default:
+            throw new Error(`Unknown step: "${step}". Valid steps: auth, db, setup, getting-started, mcp, skills, migrations, neon-auth, status, finalize`);
+    }
+}

package/dist/init/skills.js

@@ -0,0 +1,248 @@
+import { existsSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { log, spinner } from "@clack/prompts";
+import { execa } from "execa";
+import { dim } from "yoctocolors";
+import { getSkillsAgentName as getSkillsAgentNameFromId } from "./agents.js";
+/**
+ * Ensures the `skills` CLI is globally installed so npx doesn't need
+ * to download it (which can fail behind corporate proxies / sandboxes).
+ */
+async function ensureSkillsCli() {
+    try {
+        await execa("skills", ["--version"], { stdio: "pipe", timeout: 5000 });
+    }
+    catch {
+        // Not installed — install it globally
+        try {
+            await execa("npm", ["install", "-g", "skills"], {
+                stdio: "pipe",
+                timeout: 60000,
+            });
+        }
+        catch {
+            // Best effort — npx will fall back to downloading
+        }
+    }
+}
+/** Base skills installed for all invocations */
+const BASE_SKILLS = ["neon", "neon-postgres"];
+/** Additional skills installed for preview (non-bootstrap) invocations */
+const PREVIEW_SKILLS = [
+    "neon-object-storage",
+    "neon-functions",
+    "neon-ai-gateway",
+];
+/** Returns the skill list based on whether preview mode is active */
+export function getSkillList(preview) {
+    return preview ? [...BASE_SKILLS, ...PREVIEW_SKILLS] : BASE_SKILLS;
+}
+const SKILL_BASE_URL = "https://neon.com/docs/ai/skills/neon-postgres/references";
+export const SKILL_REFERENCE_URLS = {
+    gettingStarted: `${SKILL_BASE_URL}/getting-started.md`,
+    connectionMethods: `${SKILL_BASE_URL}/connection-methods.md`,
+    neonAuth: `${SKILL_BASE_URL}/neon-auth.md`,
+    serverlessDriver: `${SKILL_BASE_URL}/neon-serverless.md`,
+    neonCli: `${SKILL_BASE_URL}/neon-cli.md`,
+    devtools: `${SKILL_BASE_URL}/devtools.md`,
+    branching: `${SKILL_BASE_URL}/branching.md`,
+    neonJs: `${SKILL_BASE_URL}/neon-js.md`,
+};
+/**
+ * Maps Editor display names to the skills CLI agent name.
+ */
+function editorToSkillsAgent(editor) {
+    switch (editor) {
+        case "Cursor":
+            return "cursor";
+        case "VS Code":
+        case "GitHub Copilot CLI":
+            return "github-copilot";
+        case "Claude CLI":
+            return "claude-code";
+        case "Codex":
+            return "codex";
+        case "OpenCode":
+            return "opencode";
+        case "Antigravity":
+            return "antigravity";
+        case "Cline":
+        case "Cline CLI":
+            return "cline";
+        case "Gemini CLI":
+            return "gemini-cli";
+        case "Goose":
+            return "goose";
+        case "Claude Desktop":
+            return "claude-code";
+        case "MCPorter":
+            return "mcporter";
+        case "Zed":
+            return "zed";
+        default:
+            return "";
+    }
+}
+/**
+ * Installs Neon agent skills using Vercel's skills CLI.
+ */
+export async function installAgentSkills(selectedEditors, options) {
+    const quiet = options?.json === true;
+    const editorsWithSkills = selectedEditors.filter((e) => editorToSkillsAgent(e) !== "");
+    if (editorsWithSkills.length === 0) {
+        return true;
+    }
+    const skillsSpinner = quiet ? null : spinner();
+    skillsSpinner?.start("Installing agent skills for Neon in this project...");
+    let anyFailed = false;
+    await ensureSkillsCli();
+    const skills = getSkillList(options?.preview);
+    for (const editor of editorsWithSkills) {
+        const agentName = editorToSkillsAgent(editor);
+        // Install one skill at a time — the skills CLI has a bug with multiple
+        // --skill flags where it creates directories but doesn't copy all SKILL.md files.
+        for (const skill of skills) {
+            try {
+                await execa("skills", [
+                    "add",
+                    "neondatabase/agent-skills",
+                    "--skill",
+                    skill,
+                    "--agent",
+                    agentName,
+                    ...(options?.scope === "global" ? ["-g"] : []),
+                    "-y",
+                ], {
+                    stdio: "pipe",
+                    timeout: 120000,
+                });
+            }
+            catch (error) {
+                if (!quiet)
+                    log.error(`Failed to install skill ${skill} for ${editor}: ${error instanceof Error ? error.message : "Unknown error"}`);
+                anyFailed = true;
+            }
+        }
+    }
+    if (anyFailed) {
+        skillsSpinner?.stop("Agent skills installation for this project completed with errors");
+        if (!quiet)
+            log.info("You can manually install skills by running: npx skills add neondatabase/agent-skills --skill neon --skill neon-postgres");
+        return false;
+    }
+    skillsSpinner?.stop(dim("Agent skills installed ✓"));
+    return true;
+}
+// ---------------------------------------------------------------------------
+// Evergreen skills: ensure skills are up to date (at most once per 12 hours)
+// ---------------------------------------------------------------------------
+const SKILLS_FRESHNESS_MS = 12 * 60 * 60 * 1000; // 12 hours
+/**
+ * Agent skills directory paths by agent, keyed by scope.
+ * These are the directories that `skills add` writes to.
+ */
+const GLOBAL_SKILLS_DIRS = (() => {
+    const home = process.env.HOME || process.env.USERPROFILE || "";
+    // .agents/skills is the generic directory used by multiple agents
+    const agentsDir = resolve(home, ".agents", "skills");
+    return {
+        cursor: [resolve(home, ".cursor", "skills"), agentsDir],
+        "claude-code": [resolve(home, ".claude", "skills"), agentsDir],
+        "github-copilot": [resolve(home, ".vscode", "skills"), agentsDir],
+        codex: [resolve(home, ".codex", "skills"), agentsDir],
+        cline: [resolve(home, ".cline", "skills"), agentsDir],
+    };
+})();
+/**
+ * Checks whether skills were recently updated (within the freshness window).
+ * Checks both project-level (skills-lock.json mtime) and global (skills dir mtime).
+ */
+function skillsAreFresh(agent, requiredSkills) {
+    const now = Date.now();
+    const cwd = process.cwd();
+    const projectSkillDirs = [".agents", ".cursor", ".claude"];
+    // Check project-level: ALL required skills must exist on disk
+    // and skills-lock.json must be recent
+    const lockPath = resolve(cwd, "skills-lock.json");
+    if (existsSync(lockPath)) {
+        try {
+            const mtime = statSync(lockPath).mtimeMs;
+            if (now - mtime < SKILLS_FRESHNESS_MS) {
+                const allExist = requiredSkills.every((skill) => projectSkillDirs.some((dir) => existsSync(resolve(cwd, dir, "skills", skill, "SKILL.md"))));
+                if (allExist)
+                    return true;
+            }
+        }
+        catch { }
+    }
+    // Check global: ALL required skills must exist in agent-specific dirs
+    const agentName = getSkillsAgentNameFromId(agent);
+    const globalDirs = GLOBAL_SKILLS_DIRS[agentName] ?? [];
+    for (const dir of globalDirs) {
+        const allExist = requiredSkills.every((skill) => existsSync(resolve(dir, skill, "SKILL.md")));
+        if (allExist) {
+            // Check freshness of any one skill file
+            try {
+                const mtime = statSync(resolve(dir, requiredSkills[0], "SKILL.md")).mtimeMs;
+                if (now - mtime < SKILLS_FRESHNESS_MS)
+                    return true;
+            }
+            catch { }
+        }
+    }
+    return false;
+}
+/**
+ * Ensures Neon agent skills are up to date. Runs `skills add` if the skills
+ * haven't been updated within the freshness window (12 hours).
+ *
+ * Designed to be called from any phase handler — cheap to call repeatedly
+ * since it's a no-op when skills are fresh.
+ */
+export async function ensureSkillsUpToDate(agent, scope, preview) {
+    const resolvedAgent = agent || "cursor";
+    const skills = getSkillList(preview);
+    if (skillsAreFresh(resolvedAgent, skills))
+        return true;
+    await ensureSkillsCli();
+    const agentName = getSkillsAgentNameFromId(resolvedAgent);
+    let allOk = true;
+    // Only install skills that don't already have SKILL.md on disk.
+    // Re-installing existing skills can trigger sandbox permission prompts.
+    const home = process.env.HOME || process.env.USERPROFILE || "";
+    const cwd = process.cwd();
+    const checkDirs = scope === "global"
+        ? [
+            resolve(home, ".cursor", "skills"),
+            resolve(home, ".claude", "skills"),
+            resolve(home, ".agents", "skills"),
+        ]
+        : [
+            resolve(cwd, ".cursor", "skills"),
+            resolve(cwd, ".claude", "skills"),
+            resolve(cwd, ".agents", "skills"),
+        ];
+    const missingSkills = skills.filter((skill) => !checkDirs.some((dir) => existsSync(resolve(dir, skill, "SKILL.md"))));
+    if (missingSkills.length === 0)
+        return true;
+    // Install one skill at a time — the skills CLI has a bug with multiple
+    // --skill flags where it creates directories but doesn't copy all SKILL.md files.
+    for (const skill of missingSkills) {
+        try {
+            await execa("skills", [
+                "add",
+                "neondatabase/agent-skills",
+                "--skill",
+                skill,
+                "--agent",
+                agentName,
+                ...(scope === "global" ? ["-g"] : []),
+                "-y",
+            ], { stdio: "pipe", timeout: 120000 });
+        }
+        catch {
+            allOk = false;
+        }
+    }
+    return allOk;
+}

package/dist/init/types.js

@@ -0,0 +1 @@
+export {};