neon 3.0.0 → 3.1.0

package/dist/init/neonctl.js

@@ -1,184 +1,133 @@
+import { globalInstallCommand, resolveInvokingPackageManager } from "../utils/package_manager.js";
 import { lstatSync } from "node:fs";
 import { execa } from "execa";
+//#region src/init/neonctl.ts
 /**
- * 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";
+* 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`
+*/
+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.
- */
+* 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;
+	try {
+		const match = (await execa("neonctl", ["--version"], {
+			stdio: "pipe",
+			timeout: 5e3
+		})).stdout.trim().match(/(\d+\.\d+\.\d+)/);
+		if (match) return match[1];
+	} catch {}
+	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 };
+* Checks whether the neonctl CLI is globally installed and whether it's up to date.
+*/
+async function checkNeonctl() {
+	const currentVersion = await getNeonctlVersion();
+	if (!currentVersion) return {
+		installed: false,
+		currentVersion: null,
+		latestVersion: null,
+		needsUpdate: true
+	};
+	let latestVersion = null;
+	try {
+		latestVersion = (await execa("npm", [
+			"view",
+			"neonctl",
+			"version"
+		], {
+			stdio: "pipe",
+			timeout: 1e4
+		})).stdout.trim();
+	} catch {
+		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;
+	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.
- */
+* 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;
-    }
+	try {
+		const home = process.env.HOME || process.env.USERPROFILE || "";
+		const candidates = [`${process.env.NVM_DIR || `${home}/.nvm`}/versions/node/${process.version}/lib/node_modules/neonctl`, `${home}/.nvm/versions/node/${process.version}/lib/node_modules/neonctl`];
+		for (const candidate of candidates) try {
+			if (lstatSync(candidate).isSymbolicLink()) return true;
+		} catch {}
+		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",
-        };
-    }
+* Ensures neonctl is globally installed and up to date.
+* Uses the same package manager that invoked the init command.
+*/
+async function ensureNeonctl() {
+	if (isLocalDevSymlink()) return {
+		status: "already_current",
+		version: await getNeonctlVersion() ?? "dev"
+	};
+	const check = await checkNeonctl();
+	if (check.installed && !check.needsUpdate) return {
+		status: "already_current",
+		version: check.currentVersion ?? void 0
+	};
+	const pm = resolveInvokingPackageManager();
+	const install = globalInstallCommand(pm, "neonctl");
+	if (!install) return {
+		status: "failed",
+		error: "Could not install the Neon CLI: this machine has no package manager that can perform a global install. npm, pnpm and bun are not on PATH (yarn Berry has no global install). Install npm, pnpm or bun, then run this again."
+	};
+	const { command, args } = install;
+	try {
+		await execa(command, args, {
+			stdio: "pipe",
+			timeout: 6e4
+		});
+		const version = await getNeonctlVersion();
+		return {
+			status: check.installed ? "updated" : "installed",
+			version: version ?? void 0
+		};
+	} catch (err) {
+		return {
+			status: "failed",
+			error: err instanceof Error ? err.message : "Unknown error"
+		};
+	}
 }
+//#endregion
+export { checkNeonctl, ensureNeonctl, neonctlCmd };

package/dist/init/orchestrate.js

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