neon 8.2.0 → 8.3.1

package/README.md

@@ -1488,7 +1488,7 @@ Global options are supported with any Neon CLI command.
 
 - <a id="analytics"></a>`--analytics`
 
-  Analytics are enabled by default to gather information about the CLI commands and options that are used by our customers. This data collection assists in offering support, and allows for a better understanding of typical usage patterns so that we can improve user experience. Neon does not collect user-defined data, such as project IDs or command payloads, except the question passed to `neon ask --prompt`. To opt-out of analytics data collection, specify `--no-analytics` or `--analytics false`.
+  Analytics are enabled by default to gather information about the CLI commands and options that are used by our customers. This data collection assists in offering support, and allows for a better understanding of typical usage patterns so that we can improve user experience. Neon does not collect user-defined data, such as project IDs or command payloads, except the question passed to `neon ask --prompt`. When the CLI fails on an internal bug (a JavaScript `TypeError`, `ReferenceError`, `RangeError`, or `SyntaxError`), it also sends that error to Neon's Sentry: the error type, the message only when it is a standard JavaScript message that names nothing but code (any other message is replaced), the stack trace with file paths cut to the package (`neon/dist/...`), the CLI and Node.js versions, and whether it ran in CI or a coding agent. To opt-out of analytics data collection and error reports, specify `--no-analytics` or `--analytics false`.
 
 - <a id="version"></a>`-v, --version`
 

package/dist/analytics.js

@@ -7,6 +7,7 @@ import { getAuthContext } from "./auth_context.js";
 import { n as credentialsPath } from "./_chunks/paths-DMq0Lt7a.js";
 import "./config.js";
 import { isCurrentBranchProbe } from "./context.js";
+import { isUnexpectedError } from "./errors.js";
 import { Analytics } from "@segment/analytics-node";
 //#region src/analytics.ts
 const WRITE_KEY = "3SQXn5ejjXWLEJ8xU2PRYhAotLtTaeeV";
@@ -190,6 +191,7 @@ const analyticsMiddleware = (args) => {
 /** How long closing waits for an unfinished account lookup before aborting it. */
 const ATTRIBUTION_WAIT_MS = 1e3;
 let closing;
+const errorReports = [];
 /**
 * Send queued events, then close the client and flush. Later calls share the first close: the
 * psql launcher starts one while psql runs, and a second `closeAndFlush` would only make the SDK
@@ -198,6 +200,7 @@ let closing;
 const closeAnalytics = (opts) => {
 	const analytics = client;
 	if (!analytics) return Promise.resolve();
+	if (closing && opts?.timeout !== void 0) return untilDeadline(closing, Date.now() + opts.timeout);
 	if (!closing) {
 		const started = Date.now();
 		closing = (async () => {
@@ -215,11 +218,27 @@ const closeAnalytics = (opts) => {
 			log.debug("Flushing CLI analytics");
 			const flush = opts?.timeout === void 0 ? void 0 : { timeout: Math.max(1, opts.timeout - (Date.now() - started)) };
 			await analytics.closeAndFlush(flush);
+			await settleErrorReports(opts?.timeout === void 0 ? void 0 : started + opts.timeout);
 			log.debug("Flushed CLI analytics");
 		})();
 	}
 	return closing;
 };
+const untilDeadline = async (work, deadline) => {
+	let timer;
+	await Promise.race([work, new Promise((resolve) => {
+		timer = setTimeout(resolve, Math.max(0, deadline - Date.now()));
+	})]);
+	clearTimeout(timer);
+};
+const settleErrorReports = async (deadline) => {
+	const reports = Promise.all(errorReports);
+	if (deadline === void 0) {
+		await reports;
+		return;
+	}
+	await untilDeadline(reports, deadline);
+};
 const getErrorAnalyticsEventContext = (_args) => ({
 	version: pkg_default.version,
 	ci: isCi(),
@@ -252,6 +271,13 @@ const sendError = (err, errCode) => {
 		});
 	});
 	log.debug("Sent CLI error event: %s", errCode);
+	if (errCode === "UNKNOWN_ERROR" && isUnexpectedError(err)) {
+		const report = import("./error_reporting.js").then(({ reportUnexpectedError }) => reportUnexpectedError(err, redactCredentialTokenIds)).catch((reportError) => {
+			log.debug("Could not report the error to Sentry: %s", reportError);
+		});
+		errorReports.push(report);
+		if (closing) closing = closing.then(() => report);
+	}
 };
 const trackEvent = (event, properties) => {
 	if (!client) return;

package/dist/auth.js

@@ -1,6 +1,6 @@
 import { log } from "./log.js";
-import { sendError } from "./analytics.js";
 import { matchErrorCode } from "./errors.js";
+import { sendError } from "./analytics.js";
 import { extendTokenSet } from "./utils/auth.js";
 import { createReadStream } from "node:fs";
 import { join } from "node:path";

package/dist/commands/branches.js

@@ -5,7 +5,7 @@ import { contextBranch, readContextFile } from "../context.js";
 import { branchCreateRequest } from "../parameters.gen.js";
 import { writer } from "../writer.js";
 import { EndpointType } from "../utils/api_enums.js";
-import { looksLikeBranchId, looksLikeLSN, looksLikeTimestamp } from "../utils/formats.js";
+import { looksLikeBranchId, looksLikeLSN, looksLikeTimestamp, toIso } from "../utils/formats.js";
 import { branchIdFromProps, fillSingleProject, resolveBranchFromProps } from "../utils/enrichers.js";
 import { getComputeUnits } from "../utils/compute_units.js";
 import { psql } from "../utils/psql.js";
@@ -230,6 +230,14 @@ const list = async (props) => {
 		})
 	});
 };
+const parseAnnotation = (value) => {
+	try {
+		return JSON.parse(value);
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(`Failed to parse --annotation JSON: ${message}`);
+	}
+};
 const create = async (props) => {
 	const branches = await props.apiClient.listProjectBranches({ projectId: props.projectId }).then(({ data }) => data.branches);
 	const parentProps = (() => {
@@ -245,6 +253,7 @@ const create = async (props) => {
 		if (!branch) throw new Error(`Branch ${props.parent} not found`);
 		return { parent_id: branch.id };
 	})();
+	const annotationValue = props.annotation ? parseAnnotation(props.annotation) : void 0;
 	if (props.schemaOnly) {
 		if (!props.compute) throw new Error("Schema-only branches require a compute endpoint");
 		if (props.type !== EndpointType.ReadWrite) throw new Error("Schema-only branches require a read-write compute endpoint");
@@ -254,7 +263,7 @@ const create = async (props) => {
 			name: props.name,
 			...parentProps,
 			...props.schemaOnly ? { init_source: "schema-only" } : {},
-			...props["expires-at"] ? { expires_at: new Date(props["expires-at"]).toISOString() } : {},
+			...props["expires-at"] ? { expires_at: toIso(props["expires-at"], "--expires-at") } : {},
 			...props.protected !== void 0 ? { protected: props.protected } : {}
 		},
 		endpoints: props.compute ? [{
@@ -262,7 +271,7 @@ const create = async (props) => {
 			suspend_timeout_seconds: props.suspendTimeout === 0 ? void 0 : props.suspendTimeout,
 			...props.cu ? getComputeUnits(props.cu) : void 0
 		}] : [],
-		annotation_value: props.annotation ? JSON.parse(props.annotation) : void 0
+		annotation_value: annotationValue
 	}));
 	if (branches.find((b) => b.id === data.branch.parent_id)?.protected) log.warning("The parent branch is protected; a unique role password has been generated for the new branch.");
 	const out = writer(props);
@@ -437,7 +446,7 @@ const setExpiration = async (props) => {
 		...props,
 		id: props.branchId
 	});
-	const expiresAt = typeof props.expiresAt === "string" ? new Date(props.expiresAt).toISOString() : null;
+	const expiresAt = typeof props.expiresAt === "string" ? toIso(props.expiresAt, "--expires-at") : null;
 	const { data } = await retryOnLock(() => props.apiClient.updateProjectBranch(props.projectId, branchId, { branch: { expires_at: expiresAt } }));
 	writer(props).end(data.branch, {
 		fields: BRANCH_FIELDS,

package/dist/commands/env.js

@@ -9,9 +9,8 @@ import { t as NEON_ENV_VAR_KEYS, u as isFunctionBaseUrlKey } from "../_chunks/en
 import { ENV_PULL_KEY_HELP, ENV_PULL_SERVICES, envKeysForSelection, envPullFlagValue, ownedEnvServiceKeys, parseEnvPullKeys } from "../env_services.js";
 import { fillSingleProject, resolveBranchRef } from "../utils/enrichers.js";
 import { warnAiGateway } from "../utils/ai_gateway_notice.js";
-import { announceTargetBranch } from "../utils/branch_notice.js";
 import { i as dropClaimableUnsupported, o as resolveNeonEnvVars } from "../_chunks/env-BWqJqBDJ.js";
-import { formatPulledEnv } from "./env_output.js";
+import { formatPulledEnv, pulledBranch } from "./env_output.js";
 import { existsSync } from "node:fs";
 import chalk from "chalk";
 //#region src/commands/env.ts
@@ -135,7 +134,7 @@ const pull = async (props, opts = {}) => {
 	const selectionEnvKeys = dropped ? dropped.envKeys : props.envKeys ?? [];
 	const selectedKeys = props.services !== void 0 || props.envKeys !== void 0 ? envKeysForSelection(selectionServices, selectionEnvKeys) : void 0;
 	const branch = opts.branch ?? await resolveBranchRef(props);
-	if (opts.announce) announceTargetBranch(props, branch, "Pulling env from branch");
+	const namedBranch = opts.announce ? branch : void 0;
 	const branchId = branch.branchId;
 	const location = {
 		cwd,
@@ -164,7 +163,7 @@ const pull = async (props, opts = {}) => {
 	});
 	const neonVars = pickSelectedVars(pickNeonVars(vars), selectedKeys, props.services !== void 0 ? selectionServices : void 0);
 	if (Object.keys(neonVars).length === 0) {
-		if (!(dropped !== null && dropped.services.length === 0 && dropped.envKeys.length === 0 && dropped.skipped.length > 0)) log.info("No Neon env variables to pull for this branch (no DATABASE_URL or enabled Auth / Data API).");
+		if (!(dropped !== null && dropped.services.length === 0 && dropped.envKeys.length === 0 && dropped.skipped.length > 0)) log.info(`No Neon env variables to pull from ${namedBranch ? pulledBranch(namedBranch) : "this branch"}: no DATABASE_URL or enabled Auth / Data API.`);
 		return { status: "empty" };
 	}
 	const { written, removed } = mergeEnvFile(targetPath, neonVars, { managedKeys: managedKeysFor(selectedKeys, unreachedButCurrent(skipped, existingEnv, branchId), existingEnv, props.services !== void 0 ? selectionServices : void 0, props.envKeys !== void 0 ? selectionEnvKeys : void 0) });
@@ -174,7 +173,7 @@ const pull = async (props, opts = {}) => {
 		removed,
 		file: targetPath,
 		...credential && credential.keys.length > 0 ? { credential } : {}
-	}, cwd));
+	}, cwd, namedBranch));
 	if (!fileExisted) ensureGitignored(targetPath);
 	const gatewayBaseUrl = neonVars.NEON_AI_GATEWAY_BASE_URL;
 	const gatewayToken = neonVars.NEON_AI_GATEWAY_TOKEN;

package/dist/commands/env_output.js

@@ -3,6 +3,7 @@ import { u as isFunctionBaseUrlKey } from "../_chunks/env-HYNFtxu5.js";
 import { BRANCH_ENV_KEY, ENV_PULL_KEYS, serviceForEnvKey } from "../env_services.js";
 import { isAbsolute, relative } from "node:path";
 import { homedir } from "node:os";
+import chalk from "chalk";
 //#region src/commands/env_output.ts
 /** Wide enough for the longest label ("Object Storage") plus a gutter, so blocks align. */
 const LABEL_WIDTH = 16;
@@ -43,10 +44,12 @@ const groupKeys = (keys) => {
 	}
 	return groups;
 };
-const formatPulledEnv = (outcome, cwd) => {
+const pulledBranch = (branch) => `branch ${chalk.cyan.bold(branch.branchName)} ${chalk.dim(`(${branch.branchId}${branch.usedDefault ? ", project default" : ""})`)}`;
+const formatPulledEnv = (outcome, cwd, branch) => {
 	const fresh = new Set(outcome.credential?.fresh ?? []);
 	const count = outcome.written.length;
-	const lines = [`Pulled ${count} Neon variable${count === 1 ? "" : "s"} into ${displayPath(outcome.file, cwd)}`];
+	const source = branch ? ` from ${pulledBranch(branch)}` : "";
+	const lines = [`Pulled ${count} Neon variable${count === 1 ? "" : "s"} into ${displayPath(outcome.file, cwd)}${source}`];
 	const groups = groupKeys(outcome.written);
 	for (const group of GROUP_ORDER) {
 		const keys = groups.get(group);
@@ -61,4 +64,4 @@ const formatPulledEnv = (outcome, cwd) => {
 	return `${lines.join("\n")}\n`;
 };
 //#endregion
-export { displayPath, formatPulledEnv, row };
+export { displayPath, formatPulledEnv, pulledBranch, row };

package/dist/commands/snapshots.js

@@ -1,8 +1,8 @@
 import { t as __exportAll } from "../_chunks/rolldown-runtime-8H4AJuhK.js";
 import { log } from "../log.js";
-import { retryOnLock } from "../api.js";
+import { isNeonApiError, retryOnLock } from "../api.js";
 import { writer } from "../writer.js";
-import { looksLikeLSN, looksLikeTimestamp } from "../utils/formats.js";
+import { looksLikeBranchId, looksLikeLSN, looksLikeSnapshotId, looksLikeTimestamp, toIso } from "../utils/formats.js";
 import { branchIdResolve, fillSingleProject, resolveBranchRef } from "../utils/enrichers.js";
 import { BRANCH_FIELDS } from "./branches.js";
 //#region src/commands/snapshots.ts
@@ -152,12 +152,6 @@ const handler = (args) => {
 };
 /** Narrow an unknown parsed JSON value to a plain object without type casting. */
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-/** Normalize a user-supplied date to an ISO 8601 string, or throw a friendly error. */
-const toIso = (value, flag) => {
-	const ms = Date.parse(value);
-	if (Number.isNaN(ms)) throw new Error(`Invalid ${flag} value: "${value}". Use an RFC 3339 timestamp, e.g. 2025-12-31T23:59:59Z.`);
-	return new Date(ms).toISOString();
-};
 /**
 * Resolve a snapshot from an id **or** a name. Snapshot names are not guaranteed
 * unique, so an id match wins; a name that resolves to more than one snapshot is a
@@ -172,6 +166,25 @@ const resolveSnapshot = async (props) => {
 	if (byName.length > 1) throw new Error(`Multiple snapshots are named "${props.id}". Re-run with the snapshot id:\n${byName.map((s) => `  ${s.id}`).join("\n")}`);
 	throw new Error(`Snapshot "${props.id}" not found.\nAvailable snapshots: ${snapshots.map((s) => `${s.name} (${s.id})`).join(", ") || "none"}`);
 };
+/**
+* Runs `call` on the snapshot `props.id` names. An id goes straight to the API without the
+* listing; a 404 sends it through {@link resolveSnapshot}, since a name can look like an id.
+* When the listing has that id, the 404 was about something else (a target branch), so it stands.
+*/
+const withSnapshotId = async (props, call) => {
+	let notFound;
+	if (looksLikeSnapshotId(props.id)) try {
+		return await call(props.id);
+	} catch (err) {
+		if (!(isNeonApiError(err) && err.status === 404)) throw err;
+		notFound = err;
+	}
+	const snapshot = await resolveSnapshot(props);
+	if (notFound && snapshot.id === props.id) throw notFound;
+	return call(snapshot.id);
+};
+/** A `br-…` id needs no branch listing; a name or the context/default branch does. */
+const snapshotBranchId = async (props) => props.branch && looksLikeBranchId(props.branch) ? props.branch : (await resolveBranchRef(props)).branchId;
 const list = async (props) => {
 	const { data: { snapshots } } = await props.apiClient.listSnapshots(props.projectId);
 	writer(props).end(snapshots, {
@@ -191,10 +204,7 @@ const get = async (props) => {
 const create = async (props) => {
 	if (props.lsn !== void 0 && !looksLikeLSN(props.lsn)) throw new Error(`Invalid --lsn value: "${props.lsn}". Expected an LSN like 0/1F3C8A0.`);
 	if (props.timestamp !== void 0 && !looksLikeTimestamp(props.timestamp)) throw new Error(`Invalid --timestamp value: "${props.timestamp}". Use an RFC 3339 timestamp, e.g. 2025-01-01T00:00:00Z.`);
-	const { branchId } = await resolveBranchRef({
-		...props,
-		branch: props.branch
-	});
+	const branchId = await snapshotBranchId(props);
 	const { data } = await retryOnLock(() => props.apiClient.createSnapshot(props.projectId, branchId, {
 		name: props.name,
 		timestamp: props.timestamp,
@@ -209,12 +219,11 @@ const create = async (props) => {
 };
 const update = async (props) => {
 	if (props.name === void 0 && props.expiresAt === void 0 && !props.clearExpiration) throw new Error("Nothing to update. Pass --name, --expires-at, or --clear-expiration.");
-	const snapshot = await resolveSnapshot(props);
 	const expiresAt = props.clearExpiration ? null : props.expiresAt !== void 0 ? toIso(props.expiresAt, "--expires-at") : void 0;
-	const { data } = await retryOnLock(() => props.apiClient.updateSnapshot(props.projectId, snapshot.id, { snapshot: {
+	const { data } = await withSnapshotId(props, (snapshotId) => retryOnLock(() => props.apiClient.updateSnapshot(props.projectId, snapshotId, { snapshot: {
 		name: props.name,
 		expires_at: expiresAt
-	} }));
+	} })));
 	writer(props).end(data.snapshot, {
 		fields: SNAPSHOT_FIELDS,
 		renderColumns: { expires_at: (s) => s.expires_at || "never" }
@@ -229,17 +238,18 @@ const deleteSnapshot = async (props) => {
 	});
 };
 const restore = async (props) => {
-	const snapshot = await resolveSnapshot(props);
-	const targetBranchId = props.targetBranch ? await branchIdResolve({
-		branch: props.targetBranch,
-		projectId: props.projectId,
-		apiClient: props.apiClient
-	}) : void 0;
-	const { data } = await retryOnLock(() => props.apiClient.restoreSnapshot(props.projectId, snapshot.id, {
-		name: props.name,
-		target_branch_id: targetBranchId,
-		finalize_restore: props.finalize
-	}));
+	const { data } = await withSnapshotId(props, async (snapshotId) => {
+		const targetBranchId = props.targetBranch ? await branchIdResolve({
+			branch: props.targetBranch,
+			projectId: props.projectId,
+			apiClient: props.apiClient
+		}) : void 0;
+		return retryOnLock(() => props.apiClient.restoreSnapshot(props.projectId, snapshotId, {
+			name: props.name,
+			target_branch_id: targetBranchId,
+			finalize_restore: props.finalize
+		}));
+	});
 	const out = writer(props).write(data.branch, {
 		fields: BRANCH_FIELDS,
 		title: "restored branch"
@@ -265,10 +275,7 @@ const finalize = async (props) => {
 	});
 };
 const scheduleGet = async (props) => {
-	const { branchId } = await resolveBranchRef({
-		...props,
-		branch: props.branch
-	});
+	const branchId = await snapshotBranchId(props);
 	const { data } = await props.apiClient.getSnapshotSchedule(props.projectId, branchId);
 	writer(props).end(data.schedule, {
 		fields: SCHEDULE_FIELDS,
@@ -310,10 +317,6 @@ const parseScheduleJson = (raw) => {
 	});
 };
 const scheduleSet = async (props) => {
-	const { branchId } = await resolveBranchRef({
-		...props,
-		branch: props.branch
-	});
 	let schedule;
 	if (props.schedule) schedule = parseScheduleJson(props.schedule);
 	else if (props.frequency) {
@@ -324,6 +327,7 @@ const scheduleSet = async (props) => {
 		if (props.retention !== void 0) item.retention_seconds = props.retention;
 		schedule = [item];
 	} else throw new Error("Provide --frequency (optionally with --hour/--day/--month/--retention) or --schedule <json>.");
+	const branchId = await snapshotBranchId(props);
 	await retryOnLock(() => props.apiClient.setSnapshotSchedule(props.projectId, branchId, { schedule }));
 	writer(props).end(schedule, {
 		fields: SCHEDULE_FIELDS,