neon 2.43.0 → 2.44.0

package/README.md

@@ -644,27 +644,34 @@ The CLI holds one Neon account by default. A profile adds another, and is nothin
 ```
 ~/.config/neon/
 ├── credentials.json          # this IS the DEFAULT profile
-├── credentials.work.json     # created by `neon auth --profile work`
+├── credentials.work.json     # created by `neon profile create work`
 └── profiles.json             # created only once a second profile exists
 ```
 
 ```bash
-neon auth --profile work     # create it, or sign in again
-neon profiles list
-neon profiles remove work
+neon profile create work     # a browser sign-in, or an API key — see below
+neon profile list
+neon profile remove work
 ```
 
 ```console
-$ neon profiles list
+$ neon profile list
 Profiles
-┌────────┬─────────┬──────────────────────┬──────────┬──────────────────────────────────────┐
-│ Active │ Name    │ Account              │ SignedIn │ Credentials                          │
-├────────┼─────────┼──────────────────────┼──────────┼──────────────────────────────────────┤
-│ *      │ DEFAULT │ me@example.com       │ yes      │ ~/.config/neon/credentials.json      │
-├────────┼─────────┼──────────────────────┼──────────┼──────────────────────────────────────┤
-│        │ work    │ me@work.example.com  │ yes      │ ~/.config/neon/credentials.work.json │
-└────────┴─────────┴──────────────────────┴──────────┴──────────────────────────────────────┘
-```
+┌────────┬─────────┬───────────────────────┬─────────┬────────────────┬──────┬────────────────────────┐
+│ Active │ Name    │ Account               │ Auth    │ Scope          │ File │ Credentials            │
+├────────┼─────────┼───────────────────────┼─────────┼────────────────┼──────┼────────────────────────┤
+│ *      │ DEFAULT │ me@example.com        │ oauth   │ -              │ ok   │ credentials.json       │
+├────────┼─────────┼───────────────────────┼─────────┼────────────────┼──────┼────────────────────────┤
+│        │ work    │ me@example.com        │ api key │ account        │ ok   │ credentials.work.json  │
+├────────┼─────────┼───────────────────────┼─────────┼────────────────┼──────┼────────────────────────┤
+│        │ ci      │ org-old-flower-827148 │ api key │ project proj-1 │ ok   │ credentials.ci.json    │
+└────────┴─────────┴───────────────────────┴─────────┴────────────────┴──────┴────────────────────────┘
+```
+
+`Scope` is what a key can reach; an OAuth session has none of its own, so it shows `-`. `File`
+says whether the credentials file can be read and understood — `ok`, `invalid` or `missing` —
+which is not the same as the credential still working; only using it shows that. The table shows
+the file name, `--output json` the full path.
 
 Select one per invocation with `--profile`, or per shell with `NEON_PROFILE`. There is no `profile use` command and nothing is stored about which profile is "current", so what you type is always what runs.
 
@@ -680,7 +687,96 @@ Entries in `profiles.json` are paths, and a path may point anywhere — which is
 }
 ```
 
-`neon profiles remove` revokes the refresh token at the authorization server, not just locally. It deletes the credentials file only when the CLI created it: an adopted path like the one above is unlinked and left on disk, and the command says so. Removing the last named profile deletes `profiles.json`, returning you to the single-account layout. `neon profiles remove DEFAULT` signs you out.
+`neon profile remove` revokes what the profile holds — an OAuth refresh token at the
+authorization server, or an API key this CLI minted — rather than only forgetting it locally. A
+key you supplied is the exception and stays live, because nothing records its id; the command
+says so. It asks for confirmation first, which `--yes` skips; without a terminal on stdin, in
+CI or behind a pipe, it refuses rather than prompting into the void. It deletes the credentials
+file only when the CLI created it: an adopted path like the one above is unlinked and left on
+disk, and the command says so. Removing the last named profile deletes `profiles.json`,
+returning you to the single-account layout. `neon profile remove DEFAULT` signs you out.
+
+### A profile holds either a sign-in or an API key
+
+`neon profile create` makes a profile, and how you call it decides which kind of credential it holds. A key-backed profile is what you want for an agent, a shared machine, or anything that must never be interrupted by a browser:
+
+```bash
+neon profile create work                            # sign in with the browser, like `neon auth`
+neon profile create work --api-key "$KEY"           # store a key you already have
+echo "$KEY" | neon profile create work --api-key -  # or pipe it, keeping it out of argv
+neon profile create ci --mint                       # sign in once, keep only a minted key
+neon profile create ci --mint --org-id org-abc-123  # minted for an organization
+neon profile create ci --mint --project-id proj-1   # minted for one project only
+neon profile create work --force                    # replace it, revoking what it holds now
+neon profile rotate-key work                        # mint a replacement, revoke the old one
+```
+
+`--force` is not only a local edit: replacing a profile revokes the credential it held, so a key
+this CLI minted stops working everywhere it was pasted, and an OAuth session is signed out.
+Without `--force`, `create` refuses and names what would be revoked. To keep a working profile
+and swap only its key, use `rotate-key`.
+
+`create` and `rotate-key` print the profile they wrote, so an agent needn't follow up with
+`list`. Under `--output json` that is a record, and it never carries the secret:
+
+```console
+$ neon profile create ci --mint --org-id org-abc-123 --output json
+{"name":"ci","account":"org-abc-123","auth":"api key","scope":"org org-abc-123","keyId":3239771,"credentials":"/home/me/.config/neon/credentials.ci.json"}
+```
+
+One flag takes the key, because the shell already covers the variations: `--api-key "$(cat
+~/keys/work)"` reads a file and `--api-key "$KEY"` takes a variable. Those put the key in the
+process arguments, where `ps` and shell history can see it, so `--api-key -` reads it from stdin
+instead — the usual convention for a piped value. `--mint` avoids the question entirely, because
+the key never leaves the CLI.
+
+**A profile is one kind or the other, never both.** `type` in the credentials file states which:
+
+```json
+// oauth: what a plain `create` (or `neon auth --profile`) writes. An absent `type` means this.
+{ "access_token": "…", "refresh_token": "…", "expires_at": 1786…, "user_id": "…" }
+
+// api_key: what `--api-key` writes
+{ "type": "api_key", "api_key": "napi_…", "user_id": "…" }
+
+// api_key from `--mint --org-id`, which records the scope it was issued at
+{ "type": "api_key", "api_key": "napi_…", "key_id": 123, "org_id": "org-…" }
+```
+
+Nothing is carried over when a profile is replaced, so one profile can never hold two credentials — or two different accounts. The secret stays in that file and never goes into `profiles.json`, so listing profiles cannot leak one. Both files are written owner-only through a temporary file and a rename, which also repairs the permissions of a file created too permissively.
+
+`--mint` is the one to reach for. It signs you in through the browser once, mints a key with that session, stores only the key, and signs the session back out — so afterwards nothing about the profile can open a browser, and no half-forgotten login is left behind. `--org-id` and `--project-id` narrow what the minted key can reach, exactly as they do on [`neon api-keys create`](#api-keys); a project-scoped key cannot create projects, mint keys, or read any other project.
+
+Every key is verified against the API before it is stored, and the account it belongs to is recorded so `profile list` can show it. Only a real API key is accepted: an OAuth access token authenticates today and then expires with nothing to refresh it.
+
+`rotate-key` mints at the scope the profile already has — replacing an org key with an account key would quietly widen everything it reaches — and stores the new key before revoking the old one, so a failed write leaves the old key working.
+
+One thing it cannot do: **an organization key cannot mint its own replacement.** Neon only accepts a personal credential when creating organization keys, so rotating an org- or project-scoped profile means signing in again — `neon profile create ci --mint --org-id org-abc-123 --force`. `rotate-key` checks this before minting and says so, rather than letting the API answer with a rule you had no reason to expect.
+
+Two things the CLI cannot do for a key you supplied rather than minted. It cannot revoke it, because `GET /api_keys` exposes no prefix and a stored secret cannot be matched to a listing entry, so both `rotate-key` and `profile remove` say the old key is still live and point you at `neon api-keys list`. For a key you supplied it records the organization the API reports, but cannot know whether that key was narrowed to a single project — so `rotate-key` will not suggest an organization-wide replacement without telling you to check `neon api-keys list` first.
+
+If a stored key stops working there is nothing to refresh, so recovery is one browser sign-in: `neon profile create work --mint --force`.
+
+### Which credential an invocation uses
+
+An explicit flag always beats an environment variable:
+
+| Given | What runs |
+| --- | --- |
+| `--api-key` and `--profile` | neither — contradictory, so the command fails |
+| `--api-key` and `NEON_PROFILE` | the flag's key |
+| `--profile` and `NEON_API_KEY` | the profile |
+| `NEON_API_KEY` and `NEON_PROFILE` | the key, and the ignored profile is named in a warning |
+| `--profile` or `NEON_PROFILE` alone | that profile |
+| nothing | `DEFAULT` |
+
+Passing both flags fails rather than picking a winner: `--api-key` supplies a credential and `--profile` selects a stored one, so there is no reading of the command that makes both true.
+
+When both are only environment variables the key wins, which keeps a CI pipeline that injects `NEON_API_KEY` working even if a `NEON_PROFILE` leaks into the environment — but the disregarded profile is named on stderr rather than passed over silently.
+
+`neon auth` and the `profile` subcommands are outside all of this, because they read the same flags to mean something else: `neon auth --profile work` names where to write a credential, and `neon profile create work --api-key …` names one to store.
+
+`neon init` does not support `--profile` yet. It hands its whole auth flow to `neon-init`, which reads the default credentials directly, so passing the flag fails instead of quietly running as the default account.
 
 ## API keys (`api-keys`)
 
@@ -759,7 +855,7 @@ API keys in org-7
 | Command                                                                    | Subcommands                                                                                                  | Description                        |
 | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------- |
 | [auth](https://neon.com/docs/reference/cli-auth)                           |                                                                                                              | Authenticate                       |
-| profiles                                                                   | `list`, `remove`                                                                                             | Manage named sets of credentials   |
+| profile                                                                    | `list`, `create`, `rotate-key`, `remove`                                                                     | Manage named sets of credentials   |
 | api-keys                                                                   | `list`, `create`, `revoke`                                                                                   | Manage API keys                    |
 | [projects](https://neon.com/docs/reference/cli-projects)                   | `list`, `create`, `update`, `delete`, `get`                                                                  | Manage projects                    |
 | [ip-allow](https://neon.com/docs/reference/cli-ip-allow)                   | `list`, `add`, `remove`, `reset`                                                                             | Manage IP Allow                    |

package/dist/_shared/auth_selection.js

@@ -0,0 +1,86 @@
+/**
+ * # Which credential an invocation authenticates with
+ *
+ * Four inputs can each answer "who am I": the `--api-key` flag, `NEON_API_KEY`, the
+ * `--profile` flag, and `NEON_PROFILE`. This module decides between them, and it is pure so
+ * the decision can be tested without a filesystem, a network, or a config directory.
+ *
+ * ## The rule
+ *
+ * **An explicit flag beats an ambient environment variable.** That single rule fixes the bug
+ * this module exists for: before it, any API key — including one merely exported into the
+ * shell — silently voided `--profile`, so `neon --profile work …` would quietly run as
+ * whoever `NEON_API_KEY` belonged to and say nothing about it.
+ *
+ * | Given | What runs |
+ * | --- | --- |
+ * | `--api-key` and `--profile` | neither: contradictory explicit flags, so this throws |
+ * | `--api-key` and `NEON_PROFILE` | the flag's key |
+ * | `--profile` and `NEON_API_KEY` | the profile |
+ * | `NEON_API_KEY` and `NEON_PROFILE` | the key, and the ignored profile is named in a warning |
+ * | `--profile` or `NEON_PROFILE` alone | that profile |
+ * | nothing | `DEFAULT` |
+ *
+ * Two explicit flags throw rather than picking a winner. They express different intents —
+ * `--api-key` supplies a credential, `--profile` selects a stored one — so there is no
+ * reading of the command that makes both true, and guessing is how the original bug behaved.
+ *
+ * When both are merely ambient, the key wins. That keeps CI exactly as it was: a pipeline
+ * that injects `NEON_API_KEY` must not change behaviour because a `NEON_PROFILE` leaked into
+ * the environment. It warns instead of staying silent, because a disregarded account
+ * selection is precisely what nobody noticed last time.
+ *
+ * `auth` and the `profile` subcommands do not use any of this. They read the same flags with
+ * different meanings — `neon auth --profile work` names where to *write* a credential, and
+ * `neon profile create work --api-key …` names one to *store* — so their callers skip
+ * selection entirely rather than passing exemptions down here.
+ */
+import { DEFAULT_PROFILE } from "./profiles.js";
+const NO_INPUTS = {
+    apiKeyFlag: "",
+    apiKeyEnv: "",
+    profileEnv: "",
+};
+let inputs = NO_INPUTS;
+export const recordCredentialInputs = (recorded) => {
+    inputs = recorded;
+};
+export const credentialInputs = () => inputs;
+export const selectCredential = ({ apiKeyFlag, profileFlag, apiKeyEnv, profileEnv, }) => {
+    const flagKey = nonEmpty(apiKeyFlag);
+    const flagProfile = nonEmpty(profileFlag);
+    if (flagKey !== undefined && flagProfile !== undefined) {
+        throw new Error("Pass either --api-key or --profile, not both. --api-key supplies a credential directly; --profile selects a stored one.");
+    }
+    if (flagKey !== undefined) {
+        return { source: "explicit-api-key", apiKey: flagKey };
+    }
+    if (flagProfile !== undefined) {
+        return { source: "profile", profile: flagProfile, explicit: true };
+    }
+    const envKey = nonEmpty(apiKeyEnv);
+    const envProfile = nonEmpty(profileEnv);
+    if (envKey !== undefined) {
+        return {
+            source: "ambient-api-key",
+            apiKey: envKey,
+            ...(envProfile !== undefined ? { ignoredProfile: envProfile } : {}),
+        };
+    }
+    return {
+        source: "profile",
+        profile: envProfile ?? DEFAULT_PROFILE,
+        explicit: envProfile !== undefined,
+    };
+};
+/** The warning for an ambient key that displaced an ambient profile, or `null`. */
+export const displacedProfileWarning = (selection) => selection.source === "ambient-api-key" &&
+    selection.ignoredProfile !== undefined
+    ? `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(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === "" ? undefined : trimmed;
+}

package/dist/_shared/credentials.js

@@ -0,0 +1,209 @@
+/**
+ * # 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`.
+ */
+import { readFileSync } from "node:fs";
+import { writeSecretFile } from "./secure_file.js";
+export const OAUTH = "oauth";
+export 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.
+ */
+export const credentialKind = (credentials, at) => {
+    const declared = credentials.type;
+    if (declared === undefined || declared === OAUTH)
+        return OAUTH;
+    if (declared === API_KEY)
+        return API_KEY;
+    // The value is not quoted back. Everything in this file is secret material, and a
+    // corrupted or hand-edited file can put a key anywhere in it — including here. Naming the
+    // file is enough to act on, and it cannot leak what the file holds.
+    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.
+ */
+export const interpretCredentials = (credentials, at) => {
+    if (credentialKind(credentials, at) === OAUTH)
+        return { kind: OAUTH };
+    const apiKey = nonEmpty(credentials.api_key);
+    if (apiKey === undefined) {
+        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.
+ */
+export 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 {
+        // The parser's message is deliberately discarded. V8 quotes a window of the input
+        // around the syntax error — on Node 24 a truncated credentials file produced
+        // `Unexpected token 'a', ..."api_key":napi_SUPERS"... is not valid JSON` — and this
+        // reason is printed by `profile list` and by every failed authentication. A malformed
+        // secret file is exactly when a diagnostic must say less, not more.
+        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 };
+};
+/**
+ * The credential at `path`, or `null` when the file is not there.
+ *
+ * A damaged file is an error, not an absence. Treating it as absent — which is what this used to
+ * do — meant any read-only command could repair it by starting a browser sign-in and overwriting
+ * it, **possibly as a different account**, with the user never having asked for a repair and no
+ * way back to whatever was in the file. Failing here costs one deliberate command; the message
+ * names it.
+ *
+ * `profile list` and telemetry use {@link inspectCredentials} instead, because describing a
+ * broken credential is not the same as using one.
+ */
+export const readCredentials = (at) => {
+    const read = inspectCredentials(at.path);
+    if (read.kind === "unusable") {
+        throw new Error(`${read.reason}. ${repair(at)}`);
+    }
+    return read.kind === "ok" ? read.credentials : null;
+};
+export const writeCredentials = (path, credentials) => {
+    writeSecretFile(path, JSON.stringify(credentials));
+};
+/**
+ * Build an `api_key` credentials object. Nothing from a previous credential is carried over.
+ *
+ * The scope is stored because it is not recoverable from the secret: `rotate-key` has to mint
+ * the replacement on the same endpoint, and an org or project key minted as an account key
+ * would silently widen what the profile reaches.
+ */
+export const apiKeyCredentials = ({ apiKey, keyId, userId, scope, }) => ({
+    type: API_KEY,
+    api_key: apiKey,
+    ...(keyId !== undefined ? { key_id: keyId } : {}),
+    ...(userId !== undefined ? { user_id: userId } : {}),
+    ...(scope?.orgId !== undefined ? { org_id: scope.orgId } : {}),
+    ...(scope?.projectId !== undefined ? { project_id: scope.projectId } : {}),
+});
+/** The scope recorded on a stored credential. */
+export const scopeOf = (credentials) => ({
+    ...(typeof credentials.org_id === "string"
+        ? { orgId: credentials.org_id }
+        : {}),
+    ...(typeof credentials.project_id === "string"
+        ? { projectId: credentials.project_id }
+        : {}),
+});
+/** How to describe a scope in output. */
+export const describeScope = (scope) => {
+    if (scope.projectId !== undefined)
+        return `project ${scope.projectId}`;
+    if (scope.orgId !== undefined)
+        return `org ${scope.orgId}`;
+    return "account";
+};
+function nonEmpty(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === "" ? undefined : trimmed;
+}
+/**
+ * Whether a stored credential is the same secret as the one about to replace it.
+ *
+ * Re-storing the key a profile already holds is a no-op, not a replacement — and retiring it
+ * would revoke the credential the command has just committed to. Trimmed on both sides, because
+ * a key read from a file or a pipe arrives with a trailing newline.
+ */
+export const isSameCredential = (existingKey, replacementKey) => {
+    if (existingKey === undefined || replacementKey === undefined)
+        return false;
+    const trimmed = existingKey.trim();
+    return trimmed !== "" && trimmed === replacementKey.trim();
+};

package/dist/_shared/paths.js

@@ -0,0 +1,149 @@
+/**
+ * # 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, and so `neon-init`, which has no workspace dependencies, can use
+ * the same resolution as everything else.
+ *
+ * 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
+ * `packages/init` 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/`.
+ */
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+/** Current directory name. New files are created here. */
+export const CONFIG_DIR_NAME = "neon";
+/** Legacy directory name, read forever so existing installs keep working untouched. */
+export const LEGACY_CONFIG_DIR_NAME = "neonctl";
+/** Where files are created. See the module docs for the precedence. */
+export 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).
+ */
+export function legacyConfigDir(options = {}) {
+    if (explicitDir(options))
+        return undefined;
+    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.
+ */
+export 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(env.XDG_CONFIG_HOME);
+    if (xdg)
+        return xdg;
+    const home = nonEmpty(env.HOME) ?? nonEmpty(env.USERPROFILE);
+    return home ? join(home, ".config") : ".config";
+}
+function explicitDir(options) {
+    const env = options.env ?? process.env;
+    return (nonEmpty(options.dir) ??
+        nonEmpty(env.NEON_CONFIG_DIR) ??
+        nonEmpty(env.NEONCTL_CONFIG_DIR));
+}
+function nonEmpty(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === "" ? undefined : trimmed;
+}
+export 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.
+ */
+export 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.
+ */
+export const credentialsPath = (dir) => resolveConfigFile(CREDENTIALS_FILE, dir === defaultDir ? {} : { dir }).path;
+/**
+ * Whether a credentials file is one the CLI created, rather than a path a profile adopted.
+ *
+ * Anything that deletes a credential has to ask this first. A profile entry may point anywhere —
+ * that is what makes adopting an existing directory a one-line edit — and a file we did not
+ * create is not ours to remove.
+ */
+export const isInsideConfigDir = (configDirectory, file) => `${resolve(file)}/`.startsWith(`${resolve(configDirectory)}/`);
+/**
+ * Whether a credentials file is one the CLI owns, counting the legacy `neonctl` directory.
+ *
+ * {@link credentialsPath} deliberately reads an existing legacy file in place rather than
+ * migrating it, so for a default config directory that file is ours even though it sits outside
+ * `neon/`. Judging ownership on the current directory alone would call an install that predates
+ * the rename "adopted".
+ */
+export const isOwnedCredentialPath = (configDirectory, file) => {
+    if (isInsideConfigDir(configDirectory, file))
+        return true;
+    if (configDirectory !== defaultDir)
+        return false;
+    const legacy = legacyConfigDir();
+    return legacy !== undefined && isInsideConfigDir(legacy, file);
+};