neon 7.0.1 → 7.0.2

package/README.md

@@ -47,10 +47,17 @@ brew upgrade neonctl
 To upgrade a binary version, download the latest binary file, as described above, and replace your old binary with the new one.
 
 Global npm, pnpm, Bun, and Homebrew installs check for updates once per day.
-When an update is available, terminal commands periodically print the matching
-upgrade command. Set `NO_UPDATE_NOTIFIER=1` to disable these checks. The notifier
+When an update is available, terminal commands print the matching upgrade command
+every three days. Set `NO_UPDATE_NOTIFIER=1` to disable these checks. The notifier
 does not run in CI, for machine-readable output, or from standalone binaries.
 
+On macOS and Linux, the same terminal commands warn once a day when more than one
+global `neon` install is on PATH, listing each one in PATH order. A project's
+`node_modules/.bin`, which `npx` and package scripts add, doesn't count. When one
+of them is Homebrew, the warning recommends `brew uninstall neonctl`, which
+leaves `neon` running the other install, such as npm. While duplicates remain, the update notice is held back;
+`NO_UPDATE_NOTIFIER=1` silences both.
+
 ## Connect
 
 Run the following command to authenticate a connection to Neon:

package/dist/notices.js

@@ -0,0 +1,47 @@
+import { log } from "./log.js";
+import { writeJsonFile } from "./utils/json_file.js";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+//#region src/notices.ts
+/**
+* When each terminal notice was last shown, so a notice repeats on its own interval rather
+* than on every command. Kept apart from the update cache: that cache is tied to one install
+* source and rewritten by a background worker, while a notice can come from any copy.
+*
+* Throttling is best effort. Two commands started together can both show a due notice.
+*/
+const NOTICES_FILE = "notices.json";
+/**
+* Keeps ids this version doesn't know, so an older and a newer CLI sharing one config
+* directory don't erase each other's timestamps.
+*/
+const parseNoticeLog = (raw) => {
+	let value;
+	try {
+		value = JSON.parse(raw);
+	} catch {
+		return {};
+	}
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return {};
+	return Object.fromEntries(Object.entries(value).filter((entry) => typeof entry[1] === "number" && Number.isFinite(entry[1])));
+};
+const isNoticeDue = (shownAt, now, intervalMs) => shownAt === void 0 || now - shownAt >= intervalMs;
+const readNoticeLog = (path) => {
+	try {
+		return parseNoticeLog(readFileSync(path, "utf8"));
+	} catch {
+		return {};
+	}
+};
+const showNotice = ({ configDir, id, intervalMs, message, now = Date.now() }) => {
+	const path = join(configDir, NOTICES_FILE);
+	const shown = readNoticeLog(path);
+	if (!isNoticeDue(shown[id], now, intervalMs)) return;
+	log.warning("%s", message);
+	writeJsonFile(path, {
+		...shown,
+		[id]: now
+	}, "CLI notice log");
+};
+//#endregion
+export { isNoticeDue, parseNoticeLog, showNotice };

package/dist/update_notifier.js

@@ -1,25 +1,29 @@
 import { isCi } from "./env.js";
 import { log } from "./log.js";
-import { recommendedCliUpgradeCommand } from "./utils/package_manager.js";
-import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { detectCliInstallMethod, recommendedCliUpgradeCommand } from "./utils/package_manager.js";
+import { writeJsonFile } from "./utils/json_file.js";
+import { showNotice } from "./notices.js";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
+import which from "which";
 import semver from "semver";
 //#region src/update_notifier.ts
-const CHECK_INTERVAL_MS = 864e5;
-const NOTIFY_INTERVAL_MS = 3 * CHECK_INTERVAL_MS;
+const DAY_MS = 864e5;
+const CHECK_INTERVAL_MS = DAY_MS;
+const UPDATE_NOTICE_INTERVAL_MS = 3 * DAY_MS;
+const DUPLICATE_NOTICE_INTERVAL_MS = DAY_MS;
 const CACHE_FILE = "update-check.json";
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const parseUpdateCheckCache = (raw) => {
 	try {
 		const value = JSON.parse(raw);
-		if (!isRecord(value) || typeof value.checkedAt !== "number" || !Number.isFinite(value.checkedAt) || value.source !== "homebrew" && value.source !== "npm" || value.latestVersion !== void 0 && typeof value.latestVersion !== "string" || value.notifiedAt !== void 0 && (typeof value.notifiedAt !== "number" || !Number.isFinite(value.notifiedAt))) return;
+		if (!isRecord(value) || typeof value.checkedAt !== "number" || !Number.isFinite(value.checkedAt) || value.source !== "homebrew" && value.source !== "npm" || value.latestVersion !== void 0 && typeof value.latestVersion !== "string") return;
 		return {
 			checkedAt: value.checkedAt,
 			source: value.source,
-			...value.latestVersion === void 0 ? {} : { latestVersion: value.latestVersion },
-			...value.notifiedAt === void 0 ? {} : { notifiedAt: value.notifiedAt }
+			...value.latestVersion === void 0 ? {} : { latestVersion: value.latestVersion }
 		};
 	} catch {
 		return;
@@ -32,20 +36,7 @@ const readUpdateCheckCache = (cachePath) => {
 		return;
 	}
 };
-const writeUpdateCheckCache = (cachePath, cache) => {
-	const temporaryPath = `${cachePath}.${process.pid}.tmp`;
-	try {
-		writeFileSync(temporaryPath, `${JSON.stringify(cache)}\n`, { mode: 384 });
-		renameSync(temporaryPath, cachePath);
-		return true;
-	} catch (error) {
-		try {
-			rmSync(temporaryPath, { force: true });
-		} catch {}
-		log.debug("Could not write the CLI update cache: %s", error instanceof Error ? error.message : String(error));
-		return false;
-	}
-};
+const writeUpdateCheckCache = (cachePath, cache) => writeJsonFile(cachePath, cache, "CLI update cache");
 const formatUpdateNotice = ({ currentVersion, latestVersion, upgradeCommand }) => {
 	if (semver.valid(currentVersion) === null || semver.valid(latestVersion) === null || !semver.gt(latestVersion, currentVersion)) return;
 	return `Neon CLI update available: ${currentVersion} → ${latestVersion}\n${upgradeCommand}`;
@@ -84,6 +75,71 @@ const spawnUpdateWorker = (cachePath, source) => {
 		log.debug("Could not start the CLI update check: %s", error instanceof Error ? error.message : String(error));
 	}
 };
+const INSTALL_LABELS = {
+	homebrew: "Homebrew",
+	bun: "Bun",
+	pnpm: "pnpm",
+	npm: "npm"
+};
+/**
+* `npm exec`, `npx`, package scripts, and `dlx` prepend a project's or a cache's
+* `node_modules/.bin`, which is gone from PATH once the command ends.
+*/
+const isPackageBin = (executable) => {
+	const bin = dirname(executable);
+	return basename(bin) === ".bin" && basename(dirname(bin)) === "node_modules";
+};
+/**
+* Every distinct `command` executable on `path`, in PATH order, leaving out
+* package-local `node_modules/.bin` entries. Entries that resolve to the same
+* file (a repeated PATH directory, Homebrew's `bin` and `opt` links) count once.
+*/
+const findCliInstalls = (command, path) => {
+	const seen = /* @__PURE__ */ new Set();
+	const installs = [];
+	for (const executable of which.sync(command, {
+		all: true,
+		nothrow: true,
+		path
+	}) ?? []) {
+		if (isPackageBin(executable)) continue;
+		const target = realpathSync(executable);
+		if (seen.has(target)) continue;
+		seen.add(target);
+		installs.push({
+			method: detectCliInstallMethod(target),
+			path: executable
+		});
+	}
+	return installs;
+};
+const formatDuplicateInstallNotice = ({ installs, otherNeonctl }) => {
+	if (installs.length < 2) return void 0;
+	const lines = ["Multiple Neon CLI installs found on PATH:", ...installs.map(({ method, path }, index) => {
+		const labels = [...method === void 0 ? [] : [INSTALL_LABELS[method]], ...index === 0 ? ["first on PATH"] : []];
+		return labels.length === 0 ? `  ${path}` : `  ${path} (${labels.join(", ")})`;
+	})];
+	if (!installs.some(({ method }) => method === "homebrew")) {
+		lines.push("Keep one and uninstall the others.");
+		return lines.join("\n");
+	}
+	lines.push(installs.some(({ method }) => method === "npm") ? "Remove the Homebrew install to use npm:" : "Remove the Homebrew install:", "  brew uninstall neonctl");
+	if (!otherNeonctl) lines.push("This also removes the `neonctl` command; run `neon` instead.");
+	lines.push("Then open a new shell.");
+	return lines.join("\n");
+};
+const duplicateInstallNotice = () => {
+	try {
+		const installs = findCliInstalls("neon", process.env.PATH);
+		return formatDuplicateInstallNotice({
+			installs,
+			otherNeonctl: findCliInstalls("neonctl", process.env.PATH).some(({ method }) => method !== "homebrew")
+		});
+	} catch (error) {
+		log.debug("Could not check PATH for other Neon CLI installs: %s", error instanceof Error ? error.message : String(error));
+		return;
+	}
+};
 const isPackagedExecutable = () => "pkg" in process;
 const shouldRunUpdateNotifier = ({ commandPath, currentBranch, disabled, isCi: runningInCi, isPackaged, output, stderrIsTty, stdoutIsTty }) => !runningInCi && !disabled && !isPackaged && output === "table" && stdoutIsTty && stderrIsTty && commandPath.length > 0 && commandPath[0] !== "completion" && !isCurrentBranchProbe({
 	commandPath,
@@ -100,37 +156,43 @@ const notifyIfUpdateAvailable = ({ commandPath, configDir, currentBranch, curren
 		stderrIsTty: process.stderr.isTTY === true,
 		stdoutIsTty: process.stdout.isTTY === true
 	})) return;
+	const now = Date.now();
+	if (process.platform !== "win32") {
+		const duplicateNotice = duplicateInstallNotice();
+		if (duplicateNotice !== void 0) {
+			showNotice({
+				configDir,
+				id: "duplicate-installs",
+				intervalMs: DUPLICATE_NOTICE_INTERVAL_MS,
+				message: duplicateNotice,
+				now
+			});
+			return;
+		}
+	}
 	const command = recommendedCliUpgradeCommand(fileURLToPath(import.meta.url));
 	if (command === void 0) return;
 	const cachePath = join(configDir, CACHE_FILE);
-	const now = Date.now();
 	const source = updateSource(command);
 	const cache = cacheForUpdateSource(readUpdateCheckCache(cachePath), source);
-	let nextCache = cache;
-	if (cache?.latestVersion !== void 0 && (cache.notifiedAt === void 0 || now - cache.notifiedAt >= NOTIFY_INTERVAL_MS)) {
-		const notice = formatUpdateNotice({
-			currentVersion,
-			latestVersion: cache.latestVersion,
-			upgradeCommand: command
-		});
-		if (notice !== void 0) {
-			log.warning("%s", notice);
-			nextCache = {
-				...cache,
-				notifiedAt: now
-			};
-		}
-	}
-	if (!shouldRefreshUpdateCheck(cache, now)) {
-		if (nextCache !== cache && nextCache !== void 0) writeUpdateCheckCache(cachePath, nextCache);
-		return;
-	}
-	nextCache = {
-		...nextCache,
+	const notice = cache?.latestVersion === void 0 ? void 0 : formatUpdateNotice({
+		currentVersion,
+		latestVersion: cache.latestVersion,
+		upgradeCommand: command
+	});
+	if (notice !== void 0) showNotice({
+		configDir,
+		id: "update",
+		intervalMs: UPDATE_NOTICE_INTERVAL_MS,
+		message: notice,
+		now
+	});
+	if (!shouldRefreshUpdateCheck(cache, now)) return;
+	if (writeUpdateCheckCache(cachePath, {
+		...cache,
 		checkedAt: now,
 		source
-	};
-	if (writeUpdateCheckCache(cachePath, nextCache)) spawnUpdateWorker(cachePath, source);
+	})) spawnUpdateWorker(cachePath, source);
 };
 const recordLatestVersion = (cachePath, source, latestVersion) => {
 	if (semver.valid(latestVersion) === null) return;
@@ -142,4 +204,4 @@ const recordLatestVersion = (cachePath, source, latestVersion) => {
 	});
 };
 //#endregion
-export { cacheForUpdateSource, formatUpdateNotice, notifyIfUpdateAvailable, parseUpdateCheckCache, recordLatestVersion, shouldRefreshUpdateCheck, shouldRunUpdateNotifier, spawnUpdateWorkerProcess, writeUpdateCheckCache };
+export { cacheForUpdateSource, findCliInstalls, formatDuplicateInstallNotice, formatUpdateNotice, notifyIfUpdateAvailable, parseUpdateCheckCache, recordLatestVersion, shouldRefreshUpdateCheck, shouldRunUpdateNotifier, spawnUpdateWorkerProcess, writeUpdateCheckCache };

package/dist/utils/json_file.js

@@ -0,0 +1,20 @@
+import { log } from "../log.js";
+import { renameSync, rmSync, writeFileSync } from "node:fs";
+//#region src/utils/json_file.ts
+/** Renames a temporary file into place so a concurrent reader never sees a partial write. */
+const writeJsonFile = (path, value, description) => {
+	const temporaryPath = `${path}.${process.pid}.tmp`;
+	try {
+		writeFileSync(temporaryPath, `${JSON.stringify(value)}\n`, { mode: 384 });
+		renameSync(temporaryPath, path);
+		return true;
+	} catch (error) {
+		try {
+			rmSync(temporaryPath, { force: true });
+		} catch {}
+		log.debug("Could not write the %s: %s", description, error instanceof Error ? error.message : String(error));
+		return false;
+	}
+};
+//#endregion
+export { writeJsonFile };

package/dist/utils/package_manager.js

@@ -159,12 +159,23 @@ const resolvePackageManager = (cwd) => inferPackageManager(cwd) ?? installedPack
 * as {@link resolvePackageManager} minus the lockfile walk.
 */
 const resolveInvokingPackageManager = () => detectInvokingPackageManager() ?? installedPackageManagers()[0] ?? "npm";
+/** How the CLI file at `path` was installed globally, or undefined when it can't be told. */
+const detectCliInstallMethod = (path) => {
+	const normalized = path.replace(/\\/g, "/").toLowerCase();
+	if (normalized.includes("/cellar/neonctl/")) return "homebrew";
+	if (normalized.includes("/.bun/install/global/node_modules/neon/")) return "bun";
+	if (normalized.includes("/pnpm/global/") && normalized.includes("/.pnpm/neon@") && normalized.includes("/node_modules/neon/")) return "pnpm";
+	if (normalized.includes("/lib/node_modules/neon/") || normalized.includes("/npm/node_modules/neon/")) return "npm";
+};
+const CLI_UPGRADE_COMMANDS = {
+	homebrew: "brew upgrade neonctl",
+	bun: "bun i -g neon@latest",
+	pnpm: "pnpm i -g neon@latest",
+	npm: "npm i -g neon@latest"
+};
 const recommendedCliUpgradeCommand = (modulePath) => {
-	const path = modulePath.replace(/\\/g, "/").toLowerCase();
-	if (path.includes("/cellar/neonctl/")) return "brew upgrade neonctl";
-	if (path.includes("/.bun/install/global/node_modules/neon/")) return "bun i -g neon@latest";
-	if (path.includes("/pnpm/global/") && path.includes("/.pnpm/neon@") && path.includes("/node_modules/neon/")) return "pnpm i -g neon@latest";
-	if (path.includes("/lib/node_modules/neon/") || path.includes("/npm/node_modules/neon/")) return "npm i -g neon@latest";
+	const method = detectCliInstallMethod(modulePath);
+	return method === void 0 ? void 0 : CLI_UPGRADE_COMMANDS[method];
 };
 /**
 * The argv for an install with `pm`: every dependency in the manifest when
@@ -333,4 +344,4 @@ const runCommand = (cmd, args, cwd, env) => new Promise((resolvePromise) => {
 	});
 });
 //#endregion
-export { DO_NOT_SUBSTITUTE_HINT, MISSING_BINARY_HINT, commandEnv, detectInvokingPackageManager, detectProjectPackageManager, formatExecCommand, formatInstallCommand, globalInstallCommand, inferPackageManager, installArgs, installedPackageManagers, recommendedCliUpgradeCommand, resolveInvokingPackageManager, resolvePackageManager, runCommand };
+export { DO_NOT_SUBSTITUTE_HINT, MISSING_BINARY_HINT, commandEnv, detectCliInstallMethod, detectInvokingPackageManager, detectProjectPackageManager, formatExecCommand, formatInstallCommand, globalInstallCommand, inferPackageManager, installArgs, installedPackageManagers, recommendedCliUpgradeCommand, resolveInvokingPackageManager, resolvePackageManager, runCommand };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neon",
-  "version": "7.0.1",
+  "version": "7.0.2",
   "description": "CLI tool for Neon, the cloud backend primitives built around Lakebase Postgres",
   "keywords": [
     "neon",
@@ -65,8 +65,8 @@
     "yargs": "17.7.2",
     "yoctocolors": "^2.1.2",
     "@neon/config": "1.8.3",
-    "@neon/config-runtime": "1.7.3",
-    "@neon/sdk": "7.0.0"
+    "@neon/sdk": "7.0.0",
+    "@neon/config-runtime": "1.7.3"
   },
   "optionalDependencies": {
     "@napi-rs/keyring": "1.3.0",
@@ -99,9 +99,9 @@
     "tsx": "4.22.3",
     "typescript": "^5.9.0",
     "vitest": "^3.0.9",
+    "@neon-internals/cli-core": "0.0.0",
     "@neon-internals/env-core": "0.0.26",
     "@neon/e2e-harness": "0.0.0",
-    "@neon-internals/cli-core": "0.0.0",
     "@neon/functions": "0.11.0"
   },
   "publishConfig": {