neon 2.39.1 → 2.42.0

package/dist/commands/profile.js

@@ -0,0 +1,123 @@
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import prompts from "prompts";
+import { revokeToken } from "../auth.js";
+import { isCi } from "../env.js";
+import { log } from "../log.js";
+import { DEFAULT_PROFILE, listProfiles, onlyDefaultRemains, profilesFilePath, readProfiles, resolveProfile, selectProfileName, } from "../profiles.js";
+import { writer } from "../writer.js";
+export const command = "profile";
+export const aliases = ["profiles"];
+export const describe = "Manage named sets of Neon credentials";
+export const builder = (argv) => argv
+    .usage("$0 profile <sub-command> [options]")
+    .command("list", "List profiles, the account each holds, and where its credentials live", (y) => y, async (args) => await list(args))
+    .command("remove <name>", "Revoke a profile's token and remove it", (y) => y
+    .positional("name", {
+    describe: "Profile to remove",
+    type: "string",
+    demandOption: true,
+})
+    .option("yes", {
+    alias: "y",
+    describe: "Skip the confirmation prompt",
+    type: "boolean",
+    default: false,
+}), async (args) => await remove(args))
+    .demandCommand(1, "Run `neon profile --help` to see the subcommands.");
+export const handler = (_args) => {
+    /* subcommands only */
+};
+const list = async (props) => {
+    const active = selectProfileName(props.profile);
+    const rows = listProfiles(props.configDir).map((p) => ({
+        active: p.name === active ? "*" : "",
+        name: p.name,
+        account: p.label ?? p.userId ?? "-",
+        credentials: p.credentialsPath,
+        signedIn: existsSync(p.credentialsPath) ? "yes" : "no",
+    }));
+    writer(props).end(rows, {
+        title: "Profiles",
+        fields: ["active", "name", "account", "signedIn", "credentials"],
+    });
+};
+const remove = async (props) => {
+    const { name } = props;
+    // Resolve before touching anything: an unknown name must fail having deleted nothing.
+    const profile = resolveProfile(props.configDir, name);
+    if (!props.yes) {
+        if (isCi()) {
+            throw new Error("Refusing to remove a profile without confirmation in CI. Pass --yes.");
+        }
+        const who = profile.label ?? profile.userId ?? "unknown account";
+        const { ok } = await prompts({
+            type: "confirm",
+            name: "ok",
+            message: `Remove profile "${name}" (${who})?`,
+            initial: false,
+        });
+        if (!ok) {
+            log.info("Cancelled.");
+            return;
+        }
+    }
+    // 1. Revoke upstream, so the token dies rather than merely becoming unreachable by us.
+    //    Best-effort: a profile is often removed precisely because its access already broke.
+    const revoked = await revokeStoredToken(profile.credentialsPath, props);
+    log.info(revoked
+        ? "Revoked the OAuth token"
+        : "Could not revoke the OAuth token — removing locally anyway");
+    // 2. Delete the credentials file only if we created it. A profile pointing outside the
+    //    config directory was adopted from elsewhere; unlink it and say so, because the
+    //    secret is still on disk and silence would imply otherwise.
+    if (existsSync(profile.credentialsPath)) {
+        if (isInsideConfigDir(props.configDir, profile.credentialsPath)) {
+            rmSync(profile.credentialsPath);
+            log.info("Deleted %s", profile.credentialsPath);
+        }
+        else {
+            log.info("Left %s on disk — not created by neon", profile.credentialsPath);
+        }
+    }
+    // 3. Drop the entry, and the file once nothing but DEFAULT is left — the mirror image
+    //    of creating it lazily, so a single-account install ends up with no profiles.json.
+    const path = profilesFilePath(props.configDir);
+    const file = readProfiles(props.configDir);
+    if (file?.profiles[name]) {
+        delete file.profiles[name];
+        if (onlyDefaultRemains(file)) {
+            rmSync(path);
+            log.info('Removed "%s" — no profiles left, deleted %s', name, path);
+        }
+        else {
+            writeFileSync(path, `${JSON.stringify(file, null, 2)}\n`, {
+                mode: 0o600,
+            });
+            log.info('Removed "%s" from %s', name, path);
+        }
+    }
+    else if (name === DEFAULT_PROFILE) {
+        log.info("Signed out of DEFAULT");
+    }
+};
+const revokeStoredToken = async (credentialsPath, props) => {
+    if (!existsSync(credentialsPath))
+        return false;
+    let tokenSet;
+    try {
+        tokenSet = JSON.parse(readFileSync(credentialsPath, "utf8"));
+    }
+    catch {
+        return false;
+    }
+    return await revokeToken({
+        oauthHost: props.oauthHost,
+        clientId: props.clientId,
+        ...(props.allowUnsafeTls
+            ? { allowUnsafeTls: props.allowUnsafeTls }
+            : {}),
+    }, tokenSet);
+};
+/** Whether a credentials file is one the CLI created, rather than an adopted path. */
+const isInsideConfigDir = (configDir, file) => `${resolve(file)}/`.startsWith(`${resolve(configDir)}/`);

package/dist/config.js

@@ -1,11 +1,29 @@
 import { existsSync, mkdirSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
+import { configDir, resolveConfigFile } from "@neon/config/paths";
 import { isCi } from "./env.js";
 export const CREDENTIALS_FILE = "credentials.json";
-export const defaultDir = join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "neonctl");
-export const ensureConfigDir = ({ "config-dir": configDir, "force-auth": forceAuth, }) => {
-    if (!existsSync(configDir) && (!isCi() || forceAuth)) {
-        mkdirSync(configDir, { recursive: true });
+/**
+ * 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;
+export const ensureConfigDir = ({ "config-dir": configDirArg, "force-auth": forceAuth, }) => {
+    if (!existsSync(configDirArg) && (!isCi() || forceAuth)) {
+        mkdirSync(configDirArg, { recursive: true });
     }
 };

package/dist/config_template.js

@@ -0,0 +1,242 @@
+/**
+ * The published npm packages a `neon.ts` project needs — the `@neon/*` org names.
+ *
+ * ⚠️ These ship to users the next time `neonctl` is released, so do NOT release
+ * neonctl until `@neon/config` and `@neon/env` are published to npm — otherwise
+ * `config init` would install packages that don't exist yet. (The libraries are
+ * mid-migration from `@neondatabase/*`; track their publish before cutting a CLI
+ * release.)
+ */
+export const CONFIG_PACKAGE = "@neon/config";
+export const ENV_PACKAGE = "@neon/env";
+export const REQUIRED_PACKAGES = [CONFIG_PACKAGE, ENV_PACKAGE];
+/**
+ * A Neon service `config init` can declare in the `neon.ts` it scaffolds, spelled the way a
+ * user types it in `--services`. Kebab-case rather than the `neon.ts` field names (`aiGateway`,
+ * `buckets`) so the flag reads like a flag; {@link renderNeonConfig} owns the mapping.
+ *
+ * Postgres is absent because every branch has it, and `dataApi` is absent because enabling it
+ * with the default `authProvider: "neon"` requires `auth` — a pairing the picker would have to
+ * enforce rather than offer.
+ */
+export const NEON_SERVICES = [
+    "auth",
+    "functions",
+    "storage",
+    "ai-gateway",
+];
+/** `--services none`: declare nothing, i.e. scaffold the bare starter policy. */
+export const NO_SERVICES = "none";
+/** Slug, display name, and source path of the function scaffolded for `functions`. */
+export const FUNCTION_SLUG = "hello";
+export const FUNCTION_NAME = "Hello World";
+export const FUNCTION_FILENAME = "hello.ts";
+/** Name of the bucket scaffolded for `storage`. */
+export const BUCKET_NAME = "assets";
+/**
+ * Parse a `--services` value into a canonical service list: comma-separated
+ * {@link NEON_SERVICES} names, or {@link NO_SERVICES} on its own for none.
+ *
+ * Unknown names are rejected here rather than silently dropped — a typo'd service would
+ * otherwise scaffold a policy missing exactly the service the user asked for. The result is
+ * deduplicated and ordered by {@link NEON_SERVICES} so the rendered file doesn't depend on the
+ * order they were typed in.
+ */
+export const parseServices = (raw) => {
+    const names = raw
+        .split(",")
+        .map((name) => name.trim())
+        .filter((name) => name !== "");
+    if (names.includes(NO_SERVICES)) {
+        if (names.length > 1) {
+            throw new Error(`--services ${NO_SERVICES} cannot be combined with other services.`);
+        }
+        return [];
+    }
+    const unknown = names.filter((name) => !NEON_SERVICES.includes(name));
+    if (unknown.length > 0) {
+        throw new Error(`Unknown service${unknown.length === 1 ? "" : "s"} ${unknown.join(", ")}. ` +
+            `Supported values: ${NEON_SERVICES.join(", ")}, ${NO_SERVICES}.`);
+    }
+    return NEON_SERVICES.filter((service) => names.includes(service));
+};
+/**
+ * One indentation level in the emitted `neon.ts`. Two spaces, which is what every renderer
+ * here produces and what `config_template.format.test.ts` holds them to.
+ */
+const INDENT = "  ";
+/**
+ * Prefix each line with `level` indentation levels. Nesting is expressed as a number at the
+ * one place that knows the structure, rather than as literal spaces at every push site — a
+ * miscounted space is otherwise invisible in review and only shows up in a user's file.
+ */
+const at = (level, ...lines) => lines.map((line) => INDENT.repeat(level) + line);
+/** Wrap `body` in an object-literal block named `key`, indented from `level`. */
+const block = (level, key, body) => [
+    ...at(level, `${key}: {`),
+    ...body,
+    ...at(level, "},"),
+];
+/** The `preview` block for the selected services, or "" when none of them is a preview feature. */
+const renderPreview = (services) => {
+    const lines = [];
+    if (services.includes("ai-gateway")) {
+        lines.push(...at(2, "aiGateway: true,"));
+    }
+    if (services.includes("functions")) {
+        lines.push(...block(2, "functions", [
+            ...at(3, `${FUNCTION_SLUG}: { name: "${FUNCTION_NAME}", source: "./${FUNCTION_FILENAME}" },`),
+        ]));
+    }
+    if (services.includes("storage")) {
+        lines.push(...block(2, "buckets", [
+            ...at(3, `// "private" is the default; use "public_read" for anonymous reads`, `${BUCKET_NAME}: { access: "private" },`),
+        ]));
+    }
+    if (lines.length === 0) {
+        return "";
+    }
+    return `${block(1, "preview", lines).join("\n")}\n`;
+};
+/**
+ * Render the `neon.ts` policy `config init` writes. With no services this is the starter
+ * policy — an explicit `auth: false`, no `preview` block, and a `branch` closure that gives
+ * new non-default branches a 7-day TTL — so the picker's "skip everything" answer and a
+ * non-interactive run produce the identical file.
+ */
+export const renderNeonConfig = (services) => `import { defineConfig } from "${CONFIG_PACKAGE}/v1";
+
+export default defineConfig({
+  // Declare your Neon services here
+  auth: ${services.includes("auth")},
+${renderPreview(services)}  // Branch policy: per-branch tuning
+  branch: (branch) => {
+    if (branch.isDefault) {
+      // Default branch: no overrides, uses project defaults
+      return {};
+    }
+    if (!branch.exists) {
+      // New non-default branches: auto-expire
+      // Run \`neon checkout <name>\` to create a new branch with these settings
+      return { ttl: "7d" };
+    }
+    // Existing branch: no changes
+    return {};
+  },
+});
+`;
+/** Render a scalar the way it has to appear in TypeScript source. */
+const renderScalar = (value) => typeof value === "string" ? `"${value}"` : String(value);
+/**
+ * Render an object key. Live names are not identifiers: a Neon bucket may be called
+ * `smoke-uploads`, which as a bare key is a subtraction and a syntax error. Anything that
+ * isn't a plain identifier gets quoted.
+ */
+const renderKey = (name) => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
+/**
+ * The `branch` closure for a policy seeded from live state, or "" when the branch carries no
+ * tuning worth declaring.
+ *
+ * `protected` is read but never declared: it is a fact about one branch, while a policy
+ * `protected` applies to every branch the policy runs against. It becomes a comment instead.
+ */
+const renderSeededBranch = (view) => {
+    const settings = [];
+    if (view.branch?.parent !== undefined) {
+        settings.push(...at(2, `parent: ${renderScalar(view.branch.parent)},`));
+    }
+    if (view.branch?.ttl !== undefined) {
+        settings.push(...at(2, `ttl: ${renderScalar(view.branch.ttl)},`));
+    }
+    const compute = view.branch?.postgres?.computeSettings;
+    const computeFields = Object.entries(compute ?? {}).filter(([, value]) => value !== undefined);
+    if (computeFields.length > 0) {
+        settings.push(...block(2, "postgres", [
+            ...block(3, "computeSettings", computeFields.flatMap(([field, value]) => at(4, `${field}: ${renderScalar(value)},`))),
+        ]));
+    }
+    if (settings.length === 0) {
+        return "";
+    }
+    // An arrow returning an object literal, so the closing line is `}),` rather than `},`.
+    return `${[...at(1, "branch: () => ({"), ...settings, ...at(1, "}),")].join("\n")}\n`;
+};
+/** The `preview` block for a policy seeded from live state. */
+const renderSeededPreview = (view, branchName) => {
+    const lines = [];
+    const buckets = Object.entries(view.preview?.buckets ?? {});
+    if (buckets.length > 0) {
+        lines.push(...block(2, "buckets", buckets.flatMap(([name, bucket]) => at(3, `${renderKey(name)}: { access: "${bucket.access}" },`))));
+    }
+    // A deployed function cannot be declared from live state: `source` is a path in the
+    // user's project and the branch only knows the uploaded bundle. Listing the slugs as a
+    // commented-out block is the most a read-back can honestly produce.
+    const functions = Object.entries(view.preview?.functions ?? {});
+    if (functions.length > 0) {
+        lines.push(...at(2, `// ${branchName} has ${functions.length} deployed function${functions.length === 1 ? "" : "s"}.`, "// Declaring one needs the local source path, which the branch does not know:", "// functions: {", ...functions.map(([slug, fn]) => `//   ${renderKey(slug)}: { name: "${fn.name}", source: "./${slug}.ts" },`), "// },"));
+    }
+    if (lines.length === 0) {
+        return "";
+    }
+    return `${block(1, "preview", lines).join("\n")}\n`;
+};
+/**
+ * Render a `neon.ts` from a branch's live state (`config init --from-branch`).
+ *
+ * Only what the branch can actually report is declared. Three things are deliberately
+ * absent, each for its own reason:
+ *
+ * - **The AI Gateway** has no branch-level enabled state to read — it is always available and
+ *   credential-gated — so `pullConfig` cannot tell whether a policy would enable it.
+ * - **Functions** cannot round-trip (no `source` path on the remote); they are listed as a
+ *   commented-out block.
+ * - **`protected`** is branch state rather than policy intent, so it is reported as a comment.
+ *
+ * A branch with nothing to report (no services, no tuning) renders the starter policy rather
+ * than an empty `defineConfig({})`: seeding found nothing, and the caller says so.
+ */
+export const renderNeonConfigFromView = (view, branchName) => {
+    const services = [
+        view.auth ? "  auth: true," : "",
+        view.dataApi ? "  dataApi: true," : "",
+    ].filter((line) => line !== "");
+    const preview = renderSeededPreview(view, branchName);
+    const branch = renderSeededBranch(view);
+    if (services.length === 0 && preview === "" && branch === "") {
+        return { source: renderNeonConfig([]), seeded: false };
+    }
+    const protectedNote = view.branch?.protected
+        ? `// ${branchName} is protected on Neon. Not declared here: a policy \`protected\` would\n// apply to every branch this policy is applied to.\n`
+        : "";
+    const body = [
+        ...services,
+        ...(preview === "" ? [] : [preview.trimEnd()]),
+        ...(branch === "" ? [] : [branch.trimEnd()]),
+    ].join("\n");
+    return {
+        source: `import { defineConfig } from "${CONFIG_PACKAGE}/v1";
+
+// Seeded by \`neon config init --from-branch\` from ${branchName}.
+// The AI Gateway is not readable from a branch (always available, credential-gated), so add
+// \`preview: { aiGateway: true }\` if the policy should declare it.
+${protectedNote}export default defineConfig({
+${body}
+});
+`,
+        seeded: true,
+    };
+};
+/**
+ * The handler written alongside `neon.ts` when `functions` is selected. It has to exist:
+ * `FunctionDef.source` is only resolved when `config apply` / `deploy` bundles it, so a
+ * declared function with no file on disk fails at deploy time rather than at authoring time.
+ *
+ * A default-exported function rather than `export default { fetch }`: both are resolved (see
+ * `resolveFetchHandler`), and the bare function is less to read and less to get wrong. It is
+ * named rather than anonymous so a project's linter has nothing to say about it, and takes no
+ * parameter because a scaffold shipping an unused `req` fails a `noUnusedParameters` project.
+ */
+export const FUNCTION_TEMPLATE = `export default async function hello(): Promise<Response> {
+  return new Response("Hello from Neon Functions");
+}
+`;

package/dist/context.js

@@ -29,8 +29,26 @@ export const isCurrentBranchProbe = (args) => args.currentBranch === true &&
  * never calls the Neon API. Gated on the exact command path so the global auth
  * middleware and the single-project resolver can skip it (it runs with no API
  * client), mirroring {@link isCurrentBranchProbe}.
+ *
+ * `--from-branch` is the exception: it seeds the policy from a branch's live state, so it
+ * needs both credentials and a resolved project. The raw argv is checked alongside the parsed
+ * flag because this runs from middleware that executes before validation, where the parsed
+ * value may not be populated yet (the same reason `analytics.ts` scans argv for
+ * `--current-branch`).
+ */
+export const isConfigInit = (args) => args._[0] === "config" &&
+    args._[1] === "init" &&
+    args.fromBranch !== true &&
+    !process.argv.includes("--from-branch");
+/**
+ * `neon profile …` manages credentials on disk and never calls the Neon API, so the global
+ * auth middleware must skip it — mirroring {@link isConfigInit}.
+ *
+ * More than a nicety: without this, listing your profiles would launch a browser login, and
+ * removing a broken profile would demand you sign into it first. Removing a profile whose
+ * access has already lapsed is the main reason to remove one.
  */
-export const isConfigInit = (args) => args._[0] === "config" && args._[1] === "init";
+export const isProfileCommand = (args) => args._[0] === "profile" || args._[0] === "profiles";
 const CONTEXT_FILE = ".neon";
 const GITIGNORE_FILE = ".gitignore";
 const canAccessFile = (file) => {

package/dist/index.js

@@ -67,6 +67,11 @@ builder = builder
     group: "Global options:",
     type: "string",
     default: defaultDir,
+})
+    .option("profile", {
+    describe: "Named credentials to use, from profiles.json (default: NEON_PROFILE, else DEFAULT)",
+    group: "Global options:",
+    type: "string",
 })
     .option("force-auth", {
     describe: "Force authentication",

package/dist/profiles.js

@@ -0,0 +1,190 @@
+/**
+ * # 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 `@neon/config/paths`). Nothing is created until a second
+ * profile is, and nothing is ever moved.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
+import { resolveConfigFile } from "@neon/config/paths";
+import { credentialsPath, defaultDir } from "./config.js";
+import { log } from "./log.js";
+export const PROFILES_FILE = "profiles.json";
+/** The implicit profile. Backed by plain `credentials.json`, with or without a profiles file. */
+export 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._-]*$/;
+/** Which profile this invocation should use: `--profile` → `NEON_PROFILE` → `DEFAULT`. */
+export const selectProfileName = (flag, env = process.env) => nonEmpty(flag) ?? nonEmpty(env.NEON_PROFILE) ?? DEFAULT_PROFILE;
+export const assertValidProfileName = (name) => {
+    if (!NAME_PATTERN.test(name)) {
+        throw new Error(`Invalid profile name "${name}". Use letters, digits, dot, dash or underscore, starting with a letter or digit.`);
+    }
+};
+/** Where `profiles.json` lives for this config directory (whether or not it exists yet). */
+export const profilesFilePath = (dir) => resolveConfigFile(PROFILES_FILE, dir === defaultDir ? {} : { dir }).path;
+/**
+ * Read `profiles.json`, or `null` when there isn't one — the normal single-account state.
+ * A malformed file is reported and treated as absent rather than breaking every command;
+ * the worst case is that a named profile is "not found", which is recoverable, whereas
+ * throwing here would lock the user out of `neon auth` itself.
+ */
+export const readProfiles = (dir) => {
+    const path = profilesFilePath(dir);
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (parsed === null ||
+            typeof parsed !== "object" ||
+            Array.isArray(parsed))
+            throw new Error("not an object");
+        const profiles = parsed.profiles;
+        if (profiles === null ||
+            typeof profiles !== "object" ||
+            Array.isArray(profiles))
+            throw new Error("missing `profiles`");
+        return { version: 1, profiles };
+    }
+    catch (err) {
+        log.warning("Ignoring malformed %s: %s", path, err instanceof Error ? err.message : String(err));
+        return null;
+    }
+};
+/** Resolve a profile to an absolute credentials path. Throws when a named profile is unknown. */
+export const resolveProfile = (dir, name) => {
+    const file = readProfiles(dir);
+    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,
+        };
+    }
+    // DEFAULT works with no profiles.json at all, and keeps working when one exists but
+    // doesn't mention it — that is the pre-profiles behaviour, unchanged.
+    if (name === DEFAULT_PROFILE) {
+        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 auth --profile ${name}\`.`);
+};
+/** Default location for a new named profile's credentials file. */
+export const newProfileCredentialsPath = (dir, name) => resolve(dir, `credentials.${name}.json`);
+/**
+ * Record a profile, creating `profiles.json` if this is the first named one.
+ *
+ * When the file is created, `DEFAULT` is written explicitly and pointed at wherever
+ * `credentials.json` actually is. That matters for an install predating the directory
+ * rename: `profiles.json` is created in `neon/` while the credentials are still in
+ * `neonctl/`, so `DEFAULT` is recorded as `../neonctl/credentials.json` rather than a
+ * relative name that would resolve to a file that isn't there.
+ */
+export const upsertProfile = (dir, name, entry) => {
+    assertValidProfileName(name);
+    const path = profilesFilePath(dir);
+    const file = readProfiles(dir) ?? {
+        version: 1,
+        profiles: {
+            [DEFAULT_PROFILE]: {
+                credentials: relativeToProfiles(path, credentialsPath(dir)),
+            },
+        },
+    };
+    file.profiles[name] = {
+        credentials: relativeToProfiles(path, entry.credentials),
+        ...(entry.label ? { label: entry.label } : {}),
+        ...(entry.userId ? { userId: entry.userId } : {}),
+    };
+    writeProfiles(path, file);
+};
+/** Remove an entry. Returns false when it wasn't there. */
+export const removeProfileEntry = (dir, name) => {
+    const path = profilesFilePath(dir);
+    const file = readProfiles(dir);
+    if (!file?.profiles[name])
+        return false;
+    delete file.profiles[name];
+    writeProfiles(path, file);
+    return true;
+};
+/**
+ * True when only `DEFAULT` is left, so `profiles.json` no longer earns its place. Mirrors
+ * lazy creation: a single-account install has no profiles file, before or after.
+ */
+export const onlyDefaultRemains = (file) => {
+    const names = Object.keys(file.profiles);
+    return (names.length === 0 ||
+        (names.length === 1 && names[0] === DEFAULT_PROFILE));
+};
+export const listProfiles = (dir) => {
+    const file = readProfiles(dir);
+    if (!file)
+        return [resolveProfile(dir, DEFAULT_PROFILE)];
+    const names = Object.keys(file.profiles);
+    if (!names.includes(DEFAULT_PROFILE))
+        names.unshift(DEFAULT_PROFILE);
+    return names.map((name) => resolveProfile(dir, name));
+};
+const writeProfiles = (path, file) => {
+    writeFileSync(path, `${JSON.stringify(file, null, 2)}\n`, { mode: 0o600 });
+};
+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), "..");
+/** Keep entries relative when they sit near `profiles.json`; absolute paths stay absolute. */
+const relativeToProfiles = (profilesPath, target) => {
+    const rel = relative(resolve(profilesPath, ".."), target);
+    return rel && !isAbsolute(rel) ? rel : target;
+};
+function nonEmpty(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === "" ? undefined : trimmed;
+}

package/dist/utils/enrichers.js

@@ -42,9 +42,7 @@ export const branchIdFromProps = async (props) => {
     return props.branchId;
 };
 export const resolveBranchRef = async (props) => {
-    const branch = "branch" in props && typeof props.branch === "string"
-        ? props.branch
-        : props.id;
+    const branch = typeof props.branch === "string" ? props.branch : props.id;
     const { data } = await props.apiClient.listProjectBranches({
         projectId: props.projectId,
     });