@neondatabase/env 1.0.0 → 1.0.1

package/dist/cli.js

@@ -1,9 +1,976 @@
 #!/usr/bin/env node
-import { runEnvExport, runEnvRun } from "./lib/cli/commands.js";
-import { readFileSync } from "node:fs";
+import { c as previewCredentialScopes, i as credentialName, l as resolveBranchPolicy, n as createApiFromOptions, o as fetchEnvKeys, r as credentialEnvKeys, s as policyEnvKeys, t as NEON_ENV_VAR_KEYS, u as toEntries } from "./env.js";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
+import { spawn } from "node:child_process";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { ConfigLoadError, ErrorCode, MissingContextError, PlatformError, credentialScopesSatisfied, loadConfigFromFile } from "@neon/config/v1";
+import { homedir } from "node:os";
+//#region ../../internals/env-core/dist/reuse-secrets.js
+/**
+* Resolve a branch's env while keeping one-time secrets the caller already holds.
+*
+* {@link fetchEnvKeys} — and the public `fetchEnv` — only ever *fetch*. The Neon API returns a
+* credential's `api_token` / `s3_secret_access_key` exactly once, at mint time, so "fetching"
+* them means minting a new credential; a plain `fetchEnv` on every `neon dev` start or `env
+* pull` would leave a live credential behind each time. This is the wrapper that avoids that:
+* it looks at what the caller already has, decides what is still usable, and asks `fetchEnv`
+* for only the rest.
+*
+* The check is a real verification, not a presence test. A persisted secret is kept only when
+* it names a credential that still exists on this branch, is not revoked or expired, and
+* carries every scope the policy needs. A `.env.example` placeholder, a credential revoked in
+* the console, one copied in from another branch, or one predating a newly-enabled feature all
+* fail that check and get replaced.
+*
+* None of this needs local bookkeeping, because the secrets carry their own credential id:
+* `AWS_ACCESS_KEY_ID` **is** the credential's `tokenId` (the storage gateway authenticates
+* against the full id), and the AI Gateway token is minted as `nt_live_<tokenIdShort>_<secret>`,
+* where `tokenIdShort` is what the credentials list reports. The env source being replaced is
+* the record of what the last call issued.
+*
+* ```ts
+* import { fetchEnvReusingSecrets } from "@neon-internals/env-core/reuse-secrets";
+*
+* const { vars, credential } = await fetchEnvReusingSecrets(config, {
+*     projectId,
+*     branch: "main",
+*     env: { ...process.env, ...readEnvFile(".env") },
+* });
+* if (credential.issued) console.log(`new values for ${credential.keys.join(", ")}`);
+* ```
+*/
+async function fetchEnvReusingSecrets(config, options) {
+	const { env: source = process.env, keys: requestedKeys, revokeSuperseded = true, ...fetchOptions } = options;
+	const api = options.api ?? createApiFromOptions(options);
+	const { branch, desired } = await resolveBranchPolicy(config, options, api);
+	const allPolicyKeys = policyEnvKeys(desired);
+	const requested = requestedKeys ? new Set(requestedKeys) : null;
+	const selectedPolicyKeys = requested === null ? allPolicyKeys : allPolicyKeys.filter((key) => requested.has(key));
+	const selected = new Set(selectedPolicyKeys);
+	const K = NEON_ENV_VAR_KEYS;
+	const storageCredentialSelected = (desired.preview?.buckets.length ?? 0) > 0 && (selected.has(K.storage.accessKeyId) || selected.has(K.storage.secretAccessKey));
+	const gatewayCredentialSelected = (desired.preview?.aiGatewayEnabled ?? false) && selected.has(K.aiGateway.apiKey);
+	const secretKeys = credentialEnvKeys({
+		storage: storageCredentialSelected,
+		aiGateway: gatewayCredentialSelected
+	}).filter((key) => selected.has(key));
+	if (secretKeys.length === 0) {
+		const fetched = await fetchEnvKeys(config, fetchOptions, requested === null ? null : selectedPolicyKeys);
+		return {
+			vars: preferPersisted(toEntries(fetched), source),
+			credential: {
+				issued: false,
+				keys: [],
+				revoked: [],
+				superseded: []
+			}
+		};
+	}
+	const persisted = readPersistedSecrets(source);
+	const storageCredentialManaged = requested === null || storageCredentialSelected;
+	const gatewayCredentialManaged = requested === null || gatewayCredentialSelected;
+	const complete = (!storageCredentialSelected || Boolean(persisted.accessKeyId && persisted.secretAccessKey)) && (!gatewayCredentialSelected || Boolean(persisted.apiToken));
+	const named = storageCredentialManaged && persisted.accessKeyId !== "" || gatewayCredentialManaged && persisted.apiToken !== "" ? namedCredentials(await api.listCredentials(options.projectId, branch.id), persisted) : {
+		storage: null,
+		gateway: null
+	};
+	const reusable = complete ? reusableCredential(named, {
+		storageEnabled: storageCredentialSelected,
+		gatewayEnabled: gatewayCredentialSelected
+	}) : null;
+	const scopes = previewCredentialScopes(desired.preview, {
+		storage: storageCredentialSelected,
+		aiGateway: gatewayCredentialSelected
+	});
+	const keep = reusable !== null && credentialScopesSatisfied(reusable.scopes, scopes);
+	const fetchKeys = keep ? selectedPolicyKeys.filter((key) => !secretKeys.includes(key)) : selectedPolicyKeys;
+	const fetched = await fetchEnvKeys(config, {
+		...fetchOptions,
+		branchId: branch.id,
+		api
+	}, fetchKeys);
+	const vars = preferPersisted(toEntries(fetched), source);
+	if (keep) {
+		for (const key of secretKeys) {
+			const value = source[key];
+			if (value !== void 0) vars[key] = value;
+		}
+		return {
+			vars,
+			credential: {
+				issued: false,
+				keys: secretKeys,
+				revoked: [],
+				superseded: []
+			}
+		};
+	}
+	const ours = /* @__PURE__ */ new Set();
+	for (const meta of [storageCredentialManaged ? named.storage : null, gatewayCredentialManaged ? named.gateway : null]) if (meta !== null && meta.principalType === "user" && meta.name === credentialName(branch.name)) ours.add(meta.tokenId);
+	if (revokeSuperseded) for (const tokenId of ours) await api.revokeCredential(options.projectId, branch.id, tokenId);
+	return {
+		vars,
+		credential: {
+			issued: true,
+			keys: secretKeys,
+			revoked: revokeSuperseded ? [...ours] : [],
+			superseded: revokeSuperseded ? [] : [...ours]
+		}
+	};
+}
+/** Read the branch credential's secrets out of an env source. */
+function readPersistedSecrets(source) {
+	const storage = NEON_ENV_VAR_KEYS.storage;
+	const gateway = NEON_ENV_VAR_KEYS.aiGateway;
+	return {
+		accessKeyId: source[storage.accessKeyId] ?? "",
+		secretAccessKey: source[storage.secretAccessKey] ?? "",
+		apiToken: source[gateway.apiKey] ?? ""
+	};
+}
+/**
+* Keep a persisted value rather than overwriting it with an empty fetched one.
+*
+* Neon Auth's `base_url` is the case that needs this: integrations created before the API
+* returned it answer with an empty string, and the persisted copy is the only one left. An
+* empty fetched value never carries more information than a non-empty persisted one, so
+* preferring the latter is safe for every var — and it keeps a pull from blanking a working
+* line in someone's `.env`.
+*/
+function preferPersisted(vars, source) {
+	const out = { ...vars };
+	for (const [key, value] of Object.entries(out)) {
+		if (value !== "") continue;
+		const persisted = source[key];
+		if (persisted !== void 0 && persisted !== "") out[key] = persisted;
+	}
+	return out;
+}
+/**
+* The credential id embedded in an AI Gateway token. The API mints them as
+* `nt_live_<tokenIdShort>_<secret>`, and `tokenIdShort` is the public identifier the credentials
+* list reports — so a persisted token names the credential that issued it. Returns `null` for
+* anything not in that shape (a `.env.example` placeholder, a hand-typed value), which callers
+* treat as unverifiable.
+*/
+function gatewayTokenIdShort(apiToken) {
+	return /^nt_live_([^_]+)_.+$/.exec(apiToken)?.[1] ?? null;
+}
+/** Whether an issued credential can still be used: not revoked, not past its expiry. */
+function isLiveCredential(meta, now) {
+	if (meta.revokedAt !== void 0) return false;
+	if (meta.expiresAt === void 0) return true;
+	const expiresAt = Date.parse(meta.expiresAt);
+	return Number.isNaN(expiresAt) || expiresAt > now;
+}
+/**
+* The live credentials the persisted secrets name — at most one per half. A half that names
+* nothing contributes nothing, which is what a placeholder, a credential revoked in the
+* console, and one copied in from another branch all look like from here.
+*/
+function namedCredentials(live, persisted) {
+	const usable = live.filter((meta) => isLiveCredential(meta, Date.now()));
+	const shortId = persisted.apiToken ? gatewayTokenIdShort(persisted.apiToken) : null;
+	return {
+		storage: persisted.accessKeyId ? usable.find((meta) => meta.tokenId === persisted.accessKeyId) ?? null : null,
+		gateway: shortId ? usable.find((meta) => meta.tokenIdShort === shortId) ?? null : null
+	};
+}
+/**
+* The credential the persisted secrets can be *reused* as, or `null`.
+*
+* Strict on purpose: every half the policy enables has to name a live credential, and when both
+* features are enabled they must name the *same* one — they share a single credential, so
+* halves that disagree came from two different calls and neither can be trusted.
+*/
+function reusableCredential(named, enabled) {
+	if (enabled.storageEnabled && enabled.gatewayEnabled) return named.storage && named.gateway && named.storage.tokenId === named.gateway.tokenId ? named.storage : null;
+	if (enabled.storageEnabled) return named.storage;
+	if (enabled.gatewayEnabled) return named.gateway;
+	return null;
+}
+//#endregion
+//#region ../../internals/cli-core/dist/paths.js
+/**
+* # Where the Neon CLIs keep their files on disk
+*
+**Deliberately impure.** It reads environment variables and touches the filesystem, which
+* `@neon/config` — the package this used to be a subpath of — must never do from its root
+* export. It lives here instead of there precisely so that a policy-facing package does not
+* carry implementor-only code.
+*
+* It exists because three separate readers each grew their own answer to "where is the
+* config directory", and all three disagreed: `packages/cli` honoured `XDG_CONFIG_HOME` but
+* not `NEONCTL_CONFIG_DIR`, `packages/env` honoured the env var but not XDG, and the init
+* flow hardcoded `~/.config/neonctl`. With `XDG_CONFIG_HOME` set, the CLI wrote
+* credentials somewhere the other two never looked.
+*
+* ## The directory
+*
+* `neon` is the current name; `neonctl` is the legacy one, kept readable forever. Resolution,
+* each entry winning over the next:
+*
+* 1. An explicit directory (a `--config-dir` flag) — **exact**, no legacy fallback.
+* 2. `NEON_CONFIG_DIR` — exact.
+* 3. `NEONCTL_CONFIG_DIR` (legacy name) — exact.
+* 4. `$XDG_CONFIG_HOME/neon`, else `<home>/.config/neon`.
+*
+* An explicitly chosen directory is never paired with a fallback: `--config-dir /tmp/ci` that
+* quietly read `~/.config/neonctl` would defeat the point of passing it.
+*
+* ## The files
+*
+* {@link resolveConfigFile} answers "which path should I use for this file", and it is the
+* same answer for reading and writing:
+*
+* - Present in `neon/` → use it.
+* - Present only in `neonctl/` → **use it there, in place.** An existing credentials file is
+*   never copied or moved, so nothing is left behind to go stale and no other tool starts
+*   reading an abandoned token.
+* - Present in neither → the new location. New files only ever appear under `neon/`.
+*/
+/** Current directory name. New files are created here. */
+const CONFIG_DIR_NAME = "neon";
+/** Legacy directory name, read forever so existing installs keep working untouched. */
+const LEGACY_CONFIG_DIR_NAME = "neonctl";
+/** Where files are created. See the module docs for the precedence. */
+function configDir(options = {}) {
+	const explicit = explicitDir(options);
+	if (explicit) return explicit;
+	return join(configHome(options.env ?? process.env), CONFIG_DIR_NAME);
+}
+/**
+* The legacy directory, or `undefined` when the location was chosen explicitly (in which
+* case there is no legacy counterpart to fall back to).
+*/
+function legacyConfigDir(options = {}) {
+	if (explicitDir(options)) return void 0;
+	return join(configHome(options.env ?? process.env), LEGACY_CONFIG_DIR_NAME);
+}
+/**
+* Resolve one file inside the config directory. Prefers the current location, falls back to
+* an existing legacy file **in place**, and otherwise points at the current location so new
+* files are created there.
+*/
+function resolveConfigFile(fileName, options = {}) {
+	const dir = configDir(options);
+	const current = resolve(dir, fileName);
+	if (existsSync(current)) return {
+		path: current,
+		dir,
+		isLegacy: false,
+		exists: true
+	};
+	const legacyDir = legacyConfigDir(options);
+	if (legacyDir) {
+		const legacy = resolve(legacyDir, fileName);
+		if (existsSync(legacy)) return {
+			path: legacy,
+			dir: legacyDir,
+			isLegacy: true,
+			exists: true
+		};
+	}
+	return {
+		path: current,
+		dir,
+		isLegacy: false,
+		exists: false
+	};
+}
+/** `$XDG_CONFIG_HOME`, else `<home>/.config`. Falls back to a relative `.config` with no home. */
+function configHome(env) {
+	const xdg = nonEmpty$3(env.XDG_CONFIG_HOME);
+	if (xdg) return xdg;
+	const home = nonEmpty$3(env.HOME) ?? nonEmpty$3(env.USERPROFILE);
+	return home ? join(home, ".config") : ".config";
+}
+function explicitDir(options) {
+	const env = options.env ?? process.env;
+	return nonEmpty$3(options.dir) ?? nonEmpty$3(env.NEON_CONFIG_DIR) ?? nonEmpty$3(env.NEONCTL_CONFIG_DIR);
+}
+function nonEmpty$3(value) {
+	if (typeof value !== "string") return void 0;
+	const trimmed = value.trim();
+	return trimmed === "" ? void 0 : trimmed;
+}
+const CREDENTIALS_FILE = "credentials.json";
+/**
+* Default for `--config-dir`: `$XDG_CONFIG_HOME/neon`, else `~/.config/neon`.
+*
+* The directory was called `neonctl` until the CLI was renamed. An existing one is still read —
+* see {@link credentialsPath} — but it is never written to, moved, or deleted.
+*/
+const defaultDir = configDir();
+/**
+* Where this invocation's `credentials.json` lives.
+*
+* When `--config-dir` was left at its default, an existing file in the legacy `neonctl`
+* directory is used **in place**: an install that predates the rename keeps working, and its
+* credentials are never duplicated into a second location where one copy could go stale while
+* another tool still reads it.
+*
+* A `--config-dir` the user actually passed is used exactly as given. Falling back out of an
+* explicitly chosen directory would defeat the reason for choosing it — a CI run pointed at a
+* scratch directory must never pick up a developer's real credentials.
+*/
+const credentialsPath = (dir) => resolveConfigFile(CREDENTIALS_FILE, dir === defaultDir ? {} : { dir }).path;
+//#endregion
+//#region ../../internals/cli-core/dist/profiles.js
+/**
+* # Profiles — several Neon accounts in one config directory
+*
+* A profile is **a pointer to a credentials file**. Nothing more. That constraint is what
+* keeps the feature small: there is no mirror, no per-profile directory tree, no persistent
+* "active profile" state to fall out of sync, and no migration.
+*
+* ```
+* ~/.config/neon/
+* ├── credentials.json          # this IS the DEFAULT profile, not a copy of it
+* ├── credentials.work.json     # created by `neon auth --profile work`
+* └── profiles.json             # created only once a second profile exists
+* ```
+*
+* `profiles.json` maps a name to a path, and the path may point anywhere — which is what
+* makes adopting an existing directory a one-line edit rather than an import command:
+*
+* ```json
+* {
+*   "version": 1,
+*   "profiles": {
+*     "DEFAULT": { "credentials": "credentials.json" },
+*     "work": {
+*       "credentials": "../neonctl-databricks/credentials.json",
+*       "label": "someone@example.com"
+*     }
+*   }
+* }
+* ```
+*
+* ## Selection
+*
+* `--profile` → `NEON_PROFILE` → `DEFAULT`. Per invocation, like `AWS_PROFILE`; there is no
+* `profile use` command, so nothing persists that could disagree with what you typed.
+*
+* ## Compatibility
+*
+* An install with no `profiles.json` is already a valid `DEFAULT`-only state: `DEFAULT`
+* resolves to `credentials.json` in the config directory (including an existing one in the
+* legacy `neonctl` directory — see `./paths.ts`). Nothing is created until a second
+* profile is, and nothing is ever moved.
+*/
+const PROFILES_FILE = "profiles.json";
+/** The implicit profile. Backed by plain `credentials.json`, with or without a profiles file. */
+const DEFAULT_PROFILE = "DEFAULT";
+/** Profile names become part of a filename, so keep them boring. */
+const NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/** Where `profiles.json` lives for this config directory (whether or not it exists yet). */
+const profilesFilePath = (dir) => resolveConfigFile(PROFILES_FILE, dir === defaultDir ? {} : { dir }).path;
+/**
+* Read and classify `profiles.json` without deciding what to do about it.
+*
+* Entry keys and shapes are validated here rather than at each use. A key is a profile name,
+* and a name that `assertValidProfileName` would reject cannot have been written by this CLI —
+* it would travel into error messages as a recovery command nobody can run, and into a
+* `credentials.<name>.json` filename.
+*/
+const inspectProfiles = (dir) => {
+	const path = profilesFilePath(dir);
+	if (!existsSync(path)) return { kind: "absent" };
+	const broken = (why) => ({
+		kind: "unusable",
+		reason: `${path} could not be read as a profiles file: ${why}`
+	});
+	let contents;
+	try {
+		contents = readFileSync(path, "utf8");
+	} catch (err) {
+		const code = err.code;
+		return broken(code ? `reading it failed with ${code}` : "reading it failed");
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(contents);
+	} catch {
+		return broken("it is not valid JSON");
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return broken("it does not contain an object");
+	const profiles = parsed.profiles;
+	if (profiles === null || typeof profiles !== "object" || Array.isArray(profiles)) return broken("it has no `profiles` object");
+	for (const [name, entry] of Object.entries(profiles)) {
+		if (!NAME_PATTERN.test(name)) return broken(`"${name}" is not a valid profile name`);
+		if (entry === null || typeof entry !== "object" || typeof entry.credentials !== "string" || entry.credentials.trim() === "") return broken(`profile "${name}" has no \`credentials\` path`);
+	}
+	return {
+		kind: "ok",
+		file: {
+			version: 1,
+			profiles
+		}
+	};
+};
+/** Resolve a profile to an absolute credentials path. Throws when a named profile is unknown. */
+const resolveProfile = (dir, name) => {
+	const read = inspectProfiles(dir);
+	if (read.kind === "unusable" && name !== "DEFAULT") throw new Error(`${read.reason}. Fix or delete the file — every named profile is defined in it.`);
+	const file = read.kind === "ok" ? read.file : null;
+	const entry = file?.profiles[name];
+	if (entry) return {
+		name,
+		credentialsPath: resolveEntryPath(dir, entry.credentials),
+		...entry.label ? { label: entry.label } : {},
+		...entry.userId ? { userId: entry.userId } : {},
+		declared: true
+	};
+	if (name === "DEFAULT") return {
+		name,
+		credentialsPath: credentialsPath(dir),
+		declared: false
+	};
+	const known = file ? Object.keys(file.profiles).join(", ") : DEFAULT_PROFILE;
+	throw new Error(`Unknown profile "${name}". Known profiles: ${known}. Create it with \`neon profile create ${name}\`.`);
+};
+const resolveEntryPath = (dir, entry) => isAbsolute(entry) ? entry : resolve(profilesDir(dir), entry);
+/** `profiles.json` may sit in the legacy directory, so entries resolve against its own dir. */
+const profilesDir = (dir) => resolve(profilesFilePath(dir), "..");
+//#endregion
+//#region ../../internals/cli-core/dist/auth_selection.js
+const selectCredential = ({ apiKeyFlag, profileFlag, apiKeyEnv, profileEnv }) => {
+	const flagKey = nonEmpty$2(apiKeyFlag);
+	const flagProfile = nonEmpty$2(profileFlag);
+	if (flagKey !== void 0 && flagProfile !== void 0) throw new Error("Pass either --api-key or --profile, not both. --api-key supplies a credential directly; --profile selects a stored one.");
+	if (flagKey !== void 0) return {
+		source: "explicit-api-key",
+		apiKey: flagKey
+	};
+	if (flagProfile !== void 0) return {
+		source: "profile",
+		profile: flagProfile,
+		explicit: true
+	};
+	const envKey = nonEmpty$2(apiKeyEnv);
+	const envProfile = nonEmpty$2(profileEnv);
+	if (envKey !== void 0) return {
+		source: "ambient-api-key",
+		apiKey: envKey,
+		...envProfile !== void 0 ? { ignoredProfile: envProfile } : {}
+	};
+	return {
+		source: "profile",
+		profile: envProfile ?? "DEFAULT",
+		explicit: envProfile !== void 0
+	};
+};
+/** The warning for an ambient key that displaced an ambient profile, or `null`. */
+const displacedProfileWarning = (selection) => selection.source === "ambient-api-key" && selection.ignoredProfile !== void 0 ? `NEON_API_KEY is set, so profile "${selection.ignoredProfile}" from NEON_PROFILE was ignored. Pass --profile ${selection.ignoredProfile} to use it instead.` : null;
+function nonEmpty$2(value) {
+	if (typeof value !== "string") return void 0;
+	const trimmed = value.trim();
+	return trimmed === "" ? void 0 : trimmed;
+}
+//#endregion
+//#region ../../internals/cli-core/dist/credentials.js
+/**
+* # Stored credentials — one file per account, two kinds
+*
+* A profile points at exactly one credentials file (see `./profiles.ts`), and that file says
+* what kind of credential it holds. Adding API-key support this way rather than adding a
+* second pointer to `profiles.json` keeps a profile what it already was — one name, one path
+* — and means `profiles.json` needs no schema change at all.
+*
+* ```json
+* // oauth: every file written before this existed. An absent `type` means this.
+* { "access_token": "…", "refresh_token": "…", "expires_at": 1786…, "user_id": "…" }
+*
+* // api_key, stored by `neon profile create --api-key`
+* { "type": "api_key", "api_key": "napi_…", "user_id": "…" }
+*
+* // api_key minted by `--mint --org-id`, which records the scope it was issued at
+* { "type": "api_key", "api_key": "napi_…", "key_id": 123, "org_id": "org-…" }
+* ```
+*
+* ## One profile, one kind
+*
+* A credentials file holds an API key or an OAuth session, never both, and `type` states
+* which. An earlier draft let the two coexist — the idea being that a key could keep the
+* session it was minted from and so rotate without a browser. It did not survive review, for
+* two reasons that are worth recording so nobody rebuilds it:
+*
+* 1. **It never worked.** The resolver returned the key without testing it, so a revoked key
+*    failed to mint and never fell back to the session sitting beside it.
+* 2. **It could mix accounts.** Nothing compared the identity of the credential being written
+*    with the one already there, so a profile could hold one account's session and another's
+*    key, told apart only by a single string. Flip or lose `type` and the profile silently
+*    becomes a different person.
+*
+* Recovery from a dead key is therefore one browser login — `neon profile create <name>
+* --mint --force` — which is what the retained session was supposed to save and never did.
+*
+* ## Older releases
+*
+* A CLI predating this reads the pointer, finds no `type` it understands, ignores it, and
+* looks for `access_token`. An `api_key` profile has none, so an older release falls through
+* to its browser login rather than crashing. That it does not crash is why `credentials`
+* stays a required pointer: an entry without one makes 2.41 and 2.42 throw
+* `ERR_INVALID_ARG_TYPE` from `resolveEntryPath`.
+*/
+const OAUTH = "oauth";
+const API_KEY = "api_key";
+/**
+* Which credential in this file authenticates, by declaration alone.
+*
+* An unrecognised `type` throws rather than falling back to `oauth`. A file we cannot
+* interpret is a misconfiguration the user has to see: treating it as OAuth would send them
+* to a browser login that silently replaces a credential they meant to keep, and treating it
+* as an API key would authenticate with whatever `api_key` happened to be there.
+*
+* This deliberately does not check that an `api_key` file has a key — `neon profile list`
+* needs the kind of a file it is not about to authenticate with, and must be able to report a
+* broken one rather than throwing halfway through a table.
+*/
+const credentialKind = (credentials, at) => {
+	const declared = credentials.type;
+	if (declared === void 0 || declared === "oauth") return OAUTH;
+	if (declared === "api_key") return API_KEY;
+	throw new Error(`${at.path} declares a "type" this version does not understand. Expected "${OAUTH}" or "${API_KEY}". ${repair(at)}`);
+};
+/**
+* The way out of a credentials file that cannot be read.
+*
+* One sentence, shared by every such error, because they all have the same two answers: write
+* a new credential over it, or delete it and start again.
+*/
+const repair = (at) => `Replace it deliberately with \`neon profile create ${at.profile} --force\`, or delete the file.`;
+/**
+* Resolve what to authenticate with, validating that the declared kind is actually usable.
+*
+* An `api_key` file with no key is a hard error rather than a fall-through to OAuth: the user
+* asked for a key, and quietly opening a browser instead would replace the credential they
+* were trying to fix.
+*/
+const interpretCredentials = (credentials, at) => {
+	if (credentialKind(credentials, at) === "oauth") return { kind: OAUTH };
+	const apiKey = nonEmpty$1(credentials.api_key);
+	if (apiKey === void 0) throw new Error(`${at.path} declares "type": "${API_KEY}" but has no "api_key" value. ${repair(at)}`);
+	return {
+		kind: API_KEY,
+		apiKey
+	};
+};
+/**
+* Read and classify a credentials file, without deciding what to do about it.
+*
+* A permission or I/O error still throws: there may be a perfectly good credential here that
+* we cannot see, and treating that as absent would send the user to a browser login that
+* overwrites it.
+*/
+const inspectCredentials = (path) => {
+	let contents;
+	try {
+		contents = readFileSync(path, "utf8");
+	} catch (err) {
+		if (err.code === "ENOENT") return { kind: "absent" };
+		throw err;
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(contents);
+	} catch {
+		return {
+			kind: "unusable",
+			reason: `${path} is not valid JSON, so the credential in it cannot be read`
+		};
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return {
+		kind: "unusable",
+		reason: `${path} does not contain a credentials object`
+	};
+	return {
+		kind: "ok",
+		credentials: parsed
+	};
+};
+function nonEmpty$1(value) {
+	if (typeof value !== "string") return void 0;
+	const trimmed = value.trim();
+	return trimmed === "" ? void 0 : trimmed;
+}
+//#endregion
+//#region src/lib/cli/resolve-api-key.ts
+/**
+* Resolve the Neon API key for a `neon-env` CLI invocation.
+*
+* Precedence is the `neon` CLI's, from the same module: **an explicit flag beats an ambient
+* environment variable.** `--api-key` and `--profile` together is an error; `--profile` beats
+* `NEON_API_KEY`; `--api-key` beats `NEON_PROFILE`; two ambient sources resolve to the key.
+*
+* Sharing that decision rather than restating it is the point. An earlier version of this file
+* checked `NEON_API_KEY` before the selected profile, so `NEON_API_KEY=… neon-env run --profile
+* work` silently used the wrong account — the very bug this feature fixes in `neon`.
+*
+* The CLI owns the resolution because `@neon/config` and `@neon/env`'s root export are
+* deliberately environment- and filesystem-agnostic: they accept an explicit `apiKey` and
+* nothing else, so the ambient sources a *user* expects have to be read out here.
+*/
+function resolveApiKey(options) {
+	const env = options.env ?? process.env;
+	const selection = selectCredential({
+		...options.apiKey !== void 0 ? { apiKeyFlag: options.apiKey } : {},
+		...options.profile !== void 0 ? { profileFlag: options.profile } : {},
+		...env.NEON_API_KEY !== void 0 ? { apiKeyEnv: env.NEON_API_KEY } : {},
+		...env.NEON_PROFILE !== void 0 ? { profileEnv: env.NEON_PROFILE } : {}
+	});
+	const displaced = displacedProfileWarning(selection);
+	if (displaced !== null) (options.warn ?? ((message) => process.stderr.write(`${message}\n`)))(displaced);
+	if (selection.source !== "profile") return selection.apiKey;
+	return readStoredCredential(selection, env);
+}
+/**
+* The credential stored for the selected profile.
+*
+* Two different situations, deliberately not merged. A **missing** credential under `DEFAULT` is
+* the ordinary not-signed-in state and resolves to no key; under a profile the user named it is
+* an error, because reporting a missing credential would hide that the real problem is the name
+* they typed. A **damaged** credential is always an error: the file is there, it is not an
+* absence, and no amount of signing in elsewhere explains it.
+*/
+function readStoredCredential(selection, env) {
+	const { profile, explicit } = selection;
+	/**
+	* An *absence* is only an error when the user named the profile. Not being signed in under
+	* `DEFAULT` is the ordinary state, and the library's `PLATFORM_MISSING_API_KEY` says it
+	* better than a stack trace.
+	*/
+	const absent = (reason) => {
+		if (explicit) throw new Error(reason);
+	};
+	let path;
+	try {
+		path = profile === "DEFAULT" ? resolveConfigFile("credentials.json", { env }).path : resolveProfile(configDir({ env }), profile).credentialsPath;
+	} catch (err) {
+		throw err instanceof Error ? err : new Error(String(err));
+	}
+	const read = inspectCredentials(path);
+	if (read.kind === "absent") return absent(`Profile "${profile}" has no stored credential at ${path}. Sign in with \`neon profile create ${profile}\`.`);
+	if (read.kind === "unusable") throw new Error(`${read.reason}. Replace it deliberately with \`neon profile create ${profile} --force\`, or delete the file.`);
+	const credential = interpretCredentials(read.credentials, {
+		path,
+		profile
+	});
+	if (credential.kind === "api_key") return credential.apiKey;
+	const token = read.credentials.access_token;
+	if (typeof token === "string" && token.trim() !== "") return token.trim();
+	throw new Error(`Profile "${profile}" holds a browser sign-in with no usable token at ${path}. Sign in again with \`neon auth --profile ${profile}\`.`);
+}
+//#endregion
+//#region src/lib/cli/resolve-context.ts
+/**
+* Resolve `projectId` and `branch` for a CLI invocation. Precedence (each wins over the
+* next): explicit flag → `NEON_*` env var → `.neon[/project.json]` walked up from `cwd`.
+*
+* Returns the resolved values plus a list of human-readable reasons for any field that
+* could not be resolved (so the caller can render one combined error).
+*/
+function resolveContext(options) {
+	const env = options.env ?? process.env;
+	const file = findNeonFile(options.cwd);
+	const projectId = nonEmpty(options.projectId) ?? nonEmpty(env.NEON_PROJECT_ID) ?? file?.projectId;
+	const branch = nonEmpty(options.branch) ?? nonEmpty(env.NEON_BRANCH) ?? nonEmpty(env.NEON_BRANCH_ID) ?? file?.branch;
+	const missing = [];
+	if (!projectId) missing.push("project id — pass `--project-id`, set `NEON_PROJECT_ID`, or add `projectId` to `.neon` (run `npx neon link`).");
+	if (!branch) missing.push("branch — pass `--branch`, set `NEON_BRANCH`/`NEON_BRANCH_ID`, or add `branch` to `.neon` (run `npx neon link` / `neon checkout <branch>`).");
+	if (!projectId || !branch) return {
+		ok: false,
+		missing
+	};
+	return {
+		ok: true,
+		context: {
+			projectId,
+			branch
+		}
+	};
+}
+/**
+* Walk up from `cwd` looking for `.neon/project.json` (preferred) or `.neon` (neonctl
+* convention). Stops at the first `.git` directory or the home directory. Read-only.
+*/
+function findNeonFile(cwd) {
+	let current = resolve(cwd);
+	const stop = resolve(homedir());
+	let lastSeen = null;
+	while (true) {
+		const parsed = readNeonFileAt(resolve(current, ".neon", "project.json")) ?? readNeonFileAt(resolve(current, ".neon"));
+		if (parsed) return parsed;
+		if (current === stop) return null;
+		if (existsSync(resolve(current, ".git"))) return null;
+		const parent = dirname(current);
+		if (parent === current || parent === lastSeen) return null;
+		lastSeen = current;
+		current = parent;
+	}
+}
+function readNeonFileAt(path) {
+	if (!isFile(path)) return null;
+	let raw;
+	try {
+		raw = readFileSync(path, "utf-8");
+	} catch {
+		return null;
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return null;
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+	const obj = parsed;
+	const out = {};
+	if (typeof obj.projectId === "string" && obj.projectId !== "") out.projectId = obj.projectId;
+	const branch = typeof obj.branch === "string" && obj.branch !== "" ? obj.branch : typeof obj.branchId === "string" && obj.branchId !== "" ? obj.branchId : void 0;
+	if (branch) out.branch = branch;
+	return out;
+}
+function isFile(path) {
+	try {
+		return statSync(path).isFile();
+	} catch {
+		return false;
+	}
+}
+function nonEmpty(value) {
+	if (typeof value !== "string") return void 0;
+	const trimmed = value.trim();
+	return trimmed === "" ? void 0 : trimmed;
+}
+//#endregion
+//#region src/lib/cli/commands.ts
+/** File `env run` reads to layer one-time auth keys. Matches the Vercel/Next.js convention. */
+const DEFAULT_ENV_FILE = ".env.local";
+/**
+* Implementation of `neon-env run -- <cmd...>`. Loads `neon.ts`, fetches the env from
+* Neon, then spawns the user-supplied command with the env vars injected on top of the
+* inherited `process.env`. Stdio is inherited so interactive dev servers keep working.
+* The parent process exits with the child's exit code.
+*/
+async function runEnvRun(options, ctx) {
+	if (options.command.length === 0) return failure([
+		"`env run` requires a command to spawn.",
+		"Usage: neon-env run -- <command> [args...]",
+		"Example: neon-env run -- npm run dev"
+	].join("\n"));
+	const resolved = resolveContext({
+		cwd: ctx.cwd,
+		...options.projectId ? { projectId: options.projectId } : {},
+		...options.branch ? { branch: options.branch } : {}
+	});
+	if (!resolved.ok) return failure(["`env run` could not resolve the Neon project and branch:", ...resolved.missing.map((m) => `  - ${m}`)].join("\n"), 3);
+	let injected;
+	try {
+		injected = await loadConfigAndFetchEnv(options, ctx, resolved.context);
+	} catch (err) {
+		return handleError(err);
+	}
+	const [executable, ...args] = options.command;
+	return {
+		exitCode: await spawnAndWait(executable, args, {
+			cwd: ctx.cwd,
+			env: {
+				...process.env,
+				...injected
+			}
+		}),
+		stdout: "",
+		stderr: ""
+	};
+}
+/**
+* Implementation of `neon-env export`. Resolves the branch's Neon env the same way `run`
+* does (neon.ts policy + linked branch), then writes it to stdout — as dotenv lines or JSON —
+* instead of spawning a process, so other env tools can consume it. For example, varlock can
+* bulk-load it with `@setValuesBulk(exec("neon-env export --format json"), format=json)`.
+*/
+async function runEnvExport(options, ctx) {
+	const resolved = resolveContext({
+		cwd: ctx.cwd,
+		...options.projectId ? { projectId: options.projectId } : {},
+		...options.branch ? { branch: options.branch } : {}
+	});
+	if (!resolved.ok) return failure(["`env export` could not resolve the Neon project and branch:", ...resolved.missing.map((m) => `  - ${m}`)].join("\n"), 3);
+	let entries;
+	try {
+		entries = await loadConfigAndFetchEnv(options, ctx, resolved.context);
+	} catch (err) {
+		return handleError(err);
+	}
+	return {
+		exitCode: 0,
+		stdout: options.format === "json" ? `${JSON.stringify(entries, null, 2)}\n` : toDotenv(entries),
+		stderr: ""
+	};
+}
+/** Render an env map as dotenv `KEY=value` lines, quoting values that need it. */
+function toDotenv(entries) {
+	const lines = Object.entries(entries).map(([key, value]) => formatDotenvLine(key, value));
+	return lines.length > 0 ? `${lines.join("\n")}\n` : "";
+}
+/**
+* Render a single `KEY=value` dotenv line, double-quoting (and escaping) values that contain
+* whitespace, `#`, quotes, or `=` so connection strings round-trip through dotenv parsers.
+*/
+function formatDotenvLine(key, value) {
+	if (!/[\s#"'=]/.test(value)) return `${key}=${value}`;
+	return `${key}="${value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;
+}
+/**
+* Load `neon.ts`, then resolve the branch env for the explicitly-resolved project + branch.
+* Layers `.env.local` (next to the config file) into the env source so re-runs keep the
+* one-time secrets the Neon API only returns once — the branch credential's, and any Auth
+* values a pre-`base_url` integration can no longer report. Uses
+* {@link fetchEnvReusingSecrets} rather than a bare `fetchEnv` so a run that already has a
+* working credential verifies and keeps it instead of minting another one per invocation.
+*/
+async function loadConfigAndFetchEnv(options, ctx, resolved) {
+	const { config, resolvedPath } = await loadConfigFromFile({
+		...options.configPath ? { path: options.configPath } : {},
+		cwd: ctx.cwd
+	});
+	const envFileSource = join(dirname(resolvedPath), DEFAULT_ENV_FILE);
+	const fileEnv = existsSync(envFileSource) ? parseEnvFile(readFileSync(envFileSource, "utf-8")) : {};
+	const apiKey = resolveApiKey({
+		...options.apiKey ? { apiKey: options.apiKey } : {},
+		...options.profile ? { profile: options.profile } : {}
+	});
+	const { vars } = await fetchEnvReusingSecrets(config, {
+		projectId: resolved.projectId,
+		branch: resolved.branch,
+		env: {
+			...process.env,
+			...fileEnv
+		},
+		...ctx.api ? { api: ctx.api } : {},
+		...apiKey ? { apiKey } : {}
+	});
+	return vars;
+}
+/**
+* Spawn a child process with stdio inherited so dev servers stay interactive. Resolves
+* with the child's exit code (treating signal terminations as code 1 so the CLI surfaces
+* a non-zero exit consistently).
+*/
+function spawnAndWait(command, args, options) {
+	return new Promise((resolve) => {
+		const child = spawn(command, args, {
+			cwd: options.cwd,
+			env: options.env,
+			stdio: "inherit"
+		});
+		child.on("error", (err) => {
+			process.stderr.write(`neon-env run: failed to spawn '${command}': ${err.message}\n`);
+			resolve(1);
+		});
+		child.on("exit", (code, signal) => {
+			if (typeof code === "number") {
+				resolve(code);
+				return;
+			}
+			if (signal) {
+				process.stderr.write(`neon-env run: child terminated by signal ${signal}\n`);
+				resolve(1);
+				return;
+			}
+			resolve(1);
+		});
+	});
+}
+function parseEnvFile(body) {
+	const out = {};
+	for (const line of body.split("\n")) {
+		const parsed = parseEnvLine(line);
+		if (parsed) out[parsed.key] = parsed.value;
+	}
+	return out;
+}
+function parseEnvLine(line) {
+	const match = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/);
+	const key = match?.[1];
+	const rawValue = match?.[2];
+	if (key === void 0 || rawValue === void 0) return null;
+	return {
+		key,
+		value: unescapeEnvValue(rawValue.trim())
+	};
+}
+function unescapeEnvValue(value) {
+	if (value.length >= 2 && value.startsWith("\"") && value.endsWith("\"")) return value.slice(1, -1).replace(/\\"/g, "\"").replace(/\\\\/g, "\\");
+	if (value.length >= 2 && value.startsWith("'") && value.endsWith("'")) return value.slice(1, -1);
+	return value;
+}
+/**
+* Stable exit code per `PlatformError` code. Mirrors the table in the config package so
+* shell pipelines can branch on the specific failure mode without parsing free text.
+*/
+const EXIT_CODE_BY_PLATFORM_ERROR_CODE = {
+	[ErrorCode.MissingApiKey]: 1,
+	[ErrorCode.Unauthorized]: 6,
+	[ErrorCode.Forbidden]: 7,
+	[ErrorCode.NotFound]: 8,
+	[ErrorCode.RateLimited]: 9,
+	[ErrorCode.NetworkError]: 10,
+	[ErrorCode.ServerError]: 11,
+	[ErrorCode.Locked]: 11,
+	[ErrorCode.InternalError]: 99
+};
+function handleError(err) {
+	if (err instanceof MissingContextError) return errorResult(err, `Missing context: ${err.message}`, 3);
+	if (err instanceof ConfigLoadError) return errorResult(err, `Failed to load config: ${err.message}`, 4);
+	if (err instanceof PlatformError && err.code === ErrorCode.MissingApiKey) return errorResult(err, [
+		"No Neon API key. `neon-env` looks for one in this order:",
+		"  - the `--api-key` flag",
+		"  - the `NEON_API_KEY` environment variable",
+		"  - `credentials.json` in `NEONCTL_CONFIG_DIR` (else `~/.config/neonctl`) — run `neon auth` to create it"
+	].join("\n"), EXIT_CODE_BY_PLATFORM_ERROR_CODE[ErrorCode.MissingApiKey] ?? 1);
+	if (err instanceof PlatformError) {
+		const exitCode = EXIT_CODE_BY_PLATFORM_ERROR_CODE[err.code];
+		if (exitCode !== void 0) return errorResult(err, err.message, exitCode);
+		return errorResult(err, `[${err.code}] ${err.message}`, 5);
+	}
+	if (err instanceof Error) return errorResult(err, err.message, 1);
+	return failure(String(err), 1);
+}
+function errorResult(err, message, exitCode) {
+	const result = {
+		exitCode,
+		stdout: "",
+		stderr: `${message}\n`
+	};
+	const debug = buildDebugInfo(err);
+	if (debug) result.debugInfo = debug;
+	return result;
+}
+function buildDebugInfo(err) {
+	if (!(err instanceof Error)) return void 0;
+	const lines = [];
+	if (err instanceof PlatformError) {
+		lines.push(`code     : ${err.code}`);
+		if (Object.keys(err.details).length > 0) lines.push(`details  : ${JSON.stringify(err.details, null, 2)}`);
+	}
+	if (err.cause instanceof Error) lines.push(`cause    : ${err.cause.name}: ${err.cause.message}`);
+	if (err.stack) lines.push(err.stack);
+	return lines.length > 0 ? lines.join("\n") : void 0;
+}
+function failure(message, exitCode = 1) {
+	return {
+		exitCode,
+		stdout: "",
+		stderr: `${message}\n`
+	};
+}
+//#endregion
 //#region src/cli.ts
 const pkgVersion = readPackageVersion();
 const argv = yargs(hideBin(process.argv)).scriptName("neon-env").usage("$0 <command> [options]").parserConfiguration({ "populate--": true }).option("debug", {
@@ -49,10 +1016,9 @@ const command = String(argv._[0]);
 const cwd = process.cwd();
 let result;
 switch (command) {
-	case "run": {
-		const passthrough = Array.isArray(argv["--"]) ? argv["--"].map(String) : [];
+	case "run":
 		result = await runEnvRun({
-			command: passthrough,
+			command: Array.isArray(argv["--"]) ? argv["--"].map(String) : [],
 			...typeof argv.config === "string" ? { configPath: argv.config } : {},
 			...typeof argv["project-id"] === "string" ? { projectId: argv["project-id"] } : {},
 			...typeof argv.branch === "string" ? { branch: argv.branch } : {},
@@ -60,7 +1026,6 @@ switch (command) {
 			...typeof argv.profile === "string" ? { profile: argv.profile } : {}
 		}, { cwd });
 		break;
-	}
 	case "export":
 		result = await runEnvExport({
 			format: argv.format === "json" ? "json" : "dotenv",