neon 2.1.1 → 2.29.0

package/dist/storage_api.js

@@ -0,0 +1,147 @@
+// Typed client helpers for the branch object-storage (bucket/object) API.
+//
+// These endpoints are part of the Neon object-storage surface (the "Buckets"
+// tag in the public API). They are not yet exposed as typed methods on
+// `@neon/sdk`, so the request/response types and the thin call helpers live
+// here. They are implemented on top of the API client's low-level `request()`
+// method, which reuses the exact same authentication, base URL, headers and
+// retry behaviour as every other neonctl command. When the SDK gains these
+// methods, the call sites in `src/commands/bucket.ts` can switch over with no
+// behavioural change.
+const bucketsPath = (projectId, branchId) => `/projects/${encodeURIComponent(projectId)}/branches/${encodeURIComponent(branchId)}/buckets`;
+const bucketPath = (projectId, branchId, bucketName) => `${bucketsPath(projectId, branchId)}/${encodeURIComponent(bucketName)}`;
+/**
+ * Create a bucket on a branch.
+ *
+ * @request POST /projects/{project_id}/branches/{branch_id}/buckets
+ */
+export const createProjectBranchBucket = (apiClient, { projectId, branchId, name, accessLevel, }) => {
+    const body = { name };
+    // Omit access_level entirely so the server default (`private`) applies.
+    if (accessLevel !== undefined) {
+        body.access_level = accessLevel;
+    }
+    return apiClient.request({
+        path: bucketsPath(projectId, branchId),
+        method: "POST",
+        body,
+        format: "json",
+        secure: true,
+    });
+};
+/**
+ * List the buckets on a branch.
+ *
+ * @request GET /projects/{project_id}/branches/{branch_id}/buckets
+ */
+export const listProjectBranchBuckets = (apiClient, { projectId, branchId }) => apiClient.request({
+    path: bucketsPath(projectId, branchId),
+    method: "GET",
+    format: "json",
+    secure: true,
+});
+/**
+ * Delete a bucket from a branch.
+ *
+ * @request DELETE /projects/{project_id}/branches/{branch_id}/buckets/{bucket_name}
+ */
+export const deleteProjectBranchBucket = (apiClient, { projectId, branchId, bucketName, }) => apiClient.request({
+    path: bucketPath(projectId, branchId, bucketName),
+    method: "DELETE",
+    secure: true,
+});
+/**
+ * List objects (and collapsed folders) in a bucket on a branch.
+ *
+ * @request GET /projects/{project_id}/branches/{branch_id}/buckets/{bucket_name}/objects
+ */
+export const listProjectBranchBucketObjects = (apiClient, { projectId, branchId, bucketName, ...query }) => apiClient.request({
+    path: `${bucketPath(projectId, branchId, bucketName)}/objects`,
+    method: "GET",
+    query,
+    format: "json",
+    secure: true,
+});
+/**
+ * Download an object's raw bytes from a bucket on a branch.
+ *
+ * The server returns the body as `application/octet-stream` with a
+ * `Content-Disposition: attachment` header; the helper requests the body as a
+ * stream (`responseType: 'stream'`), so `.data` is a Node `Readable` the caller
+ * can pipe straight to disk without buffering the whole object in memory. The
+ * response headers are returned alongside so the caller can derive a filename
+ * from `Content-Disposition`.
+ *
+ * The object key may contain `/`; it is percent-encoded into a single path
+ * segment so nested keys are routed to the `{object_key}` parameter.
+ *
+ * @request GET /projects/{project_id}/branches/{branch_id}/buckets/{bucket_name}/objects/{object_key}/download
+ */
+export const getProjectBranchBucketObject = (apiClient, { projectId, branchId, bucketName, objectKey, }) => apiClient.request({
+    path: `${bucketPath(projectId, branchId, bucketName)}/objects/${encodeURIComponent(objectKey)}/download`,
+    method: "GET",
+    format: "stream",
+    secure: true,
+});
+/**
+ * Delete an object from a bucket on a branch.
+ *
+ * The object key may contain `/`; it is percent-encoded into a single path
+ * segment so nested keys are routed to the `{object_key}` parameter.
+ *
+ * @request DELETE /projects/{project_id}/branches/{branch_id}/buckets/{bucket_name}/objects/{object_key}
+ */
+export const deleteProjectBranchBucketObject = (apiClient, { projectId, branchId, bucketName, objectKey, }) => apiClient.request({
+    path: `${bucketPath(projectId, branchId, bucketName)}/objects/${encodeURIComponent(objectKey)}`,
+    method: "DELETE",
+    secure: true,
+});
+/**
+ * Delete every object under a key prefix (folder) in a bucket on a branch.
+ *
+ * `prefix` must be non-empty and end with `/`; every object on this branch
+ * whose key starts with the prefix is soft-deleted in a single call.
+ *
+ * @request DELETE /projects/{project_id}/branches/{branch_id}/buckets/{bucket_name}/objects-by-prefix
+ */
+export const deleteProjectBranchBucketObjectsByPrefix = (apiClient, { projectId, branchId, bucketName, prefix, }) => apiClient.request({
+    path: `${bucketPath(projectId, branchId, bucketName)}/objects-by-prefix`,
+    method: "DELETE",
+    query: { prefix },
+    format: "json",
+    secure: true,
+});
+/**
+ * Request a presigned PUT URL for uploading an object to a bucket on a branch.
+ *
+ * Returns the URL, the headers that must accompany the PUT for the signature to
+ * verify, and the expiry. The actual upload (a `PUT` to the returned `url` with
+ * the returned `headers` and the file stream) is performed by the caller, NOT
+ * through this api-client, since it targets the branch S3 data-plane endpoint
+ * rather than the console API. No SigV4 or credential handling happens here.
+ *
+ * The object key may contain `/`; it is percent-encoded into a single path
+ * segment so nested keys are routed to the `{object_key}` parameter.
+ *
+ * This targets the unified presign endpoint, passing `operation: "upload"` to
+ * request a presigned PUT. (The same endpoint also serves `download`, but that
+ * path is API-only and has no neonctl command.)
+ *
+ * @request POST /projects/{project_id}/branches/{branch_id}/buckets/{bucket_name}/objects/{object_key}/presign
+ */
+export const presignUpload = (apiClient, { projectId, branchId, bucketName, objectKey, contentType, expiresInSeconds, }) => {
+    const body = { operation: "upload" };
+    if (contentType !== undefined) {
+        body.content_type = contentType;
+    }
+    if (expiresInSeconds !== undefined) {
+        body.expires_in_seconds = expiresInSeconds;
+    }
+    return apiClient.request({
+        path: `${bucketPath(projectId, branchId, bucketName)}/objects/${encodeURIComponent(objectKey)}/presign`,
+        method: "POST",
+        body,
+        format: "json",
+        secure: true,
+    });
+};

package/dist/test_utils/fixtures.js

@@ -0,0 +1,122 @@
+import { fork } from "node:child_process";
+import { createServer } from "node:http";
+import { join } from "node:path";
+import emocks from "emocks";
+import express from "express";
+import strip from "strip-ansi";
+import { expect, test as originalTest } from "vitest";
+import { log } from "../log";
+/**
+ * Reserve a localhost port and close its listener, returning a URL that is guaranteed to
+ * refuse connections right now. Lets a test drive the CLI into a real `ECONNREFUSED`
+ * (the same shape a network blip produces) deterministically and fast.
+ */
+const reserveClosedPort = () => new Promise((resolve, reject) => {
+    const probe = createServer();
+    probe.on("error", reject);
+    probe.listen(0, "127.0.0.1", () => {
+        const { port } = probe.address();
+        probe.close((err) => {
+            if (err) {
+                reject(err);
+            }
+            else {
+                resolve(`http://127.0.0.1:${port}`);
+            }
+        });
+    });
+});
+export const test = originalTest.extend({
+    // eslint-disable-next-line no-empty-pattern
+    runMockServer: async ({}, use) => {
+        let startedServer;
+        await use(async (mockDir) => {
+            const app = express();
+            app.use(express.json());
+            app.use("/", emocks(join(process.cwd(), "mocks", mockDir), {
+                "404": (_req, res) => res.status(404).send({ message: "Not Found" }),
+            }));
+            const server = await new Promise((resolve) => {
+                const s = app.listen(0, () => {
+                    log.debug("Mock server listening at %d", s.address().port);
+                    resolve(s);
+                });
+            });
+            startedServer = server;
+            return server;
+        });
+        // `unreachableHost` tests never start the server, so only close it when it ran.
+        const server = startedServer;
+        if (server) {
+            await new Promise((resolve, reject) => {
+                server.close((err) => {
+                    if (err) {
+                        reject(err instanceof Error ? err : new Error(String(err)));
+                    }
+                    else {
+                        resolve();
+                    }
+                });
+            });
+        }
+    },
+    testCliCommand: async ({ runMockServer }, use) => {
+        await use(async (args, options = {}) => {
+            const apiHost = options.unreachableHost
+                ? await reserveClosedPort()
+                : `http://localhost:${(await runMockServer(options.mockDir || "main")).address().port}`;
+            let output = "";
+            let error = "";
+            const cp = fork(join(process.cwd(), "./dist/index.js"), [
+                "--api-host",
+                apiHost,
+                "--output",
+                options.output ?? (options.outputTable ? "table" : "yaml"),
+                "--api-key",
+                "test-key",
+                "--no-analytics",
+                ...args,
+            ], {
+                stdio: "pipe",
+                ...(options.cwd ? { cwd: options.cwd } : {}),
+                env: {
+                    PATH: `${join(process.cwd(), "mocks/bin")}:${process.env.PATH}`,
+                    ...(options.env ?? {}),
+                },
+            });
+            return new Promise((resolve, reject) => {
+                cp.stdout?.on("data", (data) => {
+                    output += data.toString();
+                });
+                cp.stderr?.on("data", (data) => {
+                    error += data.toString();
+                    log.error(data.toString());
+                });
+                cp.on("error", (err) => {
+                    log.error(err);
+                    throw err;
+                });
+                cp.on("close", (code) => {
+                    try {
+                        expect(code).toBe(options?.code ?? 0);
+                        expect(output).toMatchSnapshot();
+                        if (options.stderr !== undefined) {
+                            expect(strip(error).replace(/\s+/g, " ").trim()).toEqual(typeof options.stderr === "string"
+                                ? options.stderr
+                                    .toString()
+                                    .replace(/\s+/g, " ")
+                                : options.stderr);
+                        }
+                        resolve();
+                    }
+                    catch (err) {
+                        reject(err instanceof Error ? err : new Error(String(err)));
+                    }
+                });
+            }).catch((err) => {
+                log.error(err);
+                throw err;
+            });
+        });
+    },
+});

package/dist/test_utils/oauth_server.js

@@ -0,0 +1,9 @@
+import { OAuth2Server } from "oauth2-mock-server";
+import { log } from "../log";
+export const startOauthServer = async () => {
+    const server = new OAuth2Server();
+    await server.issuer.keys.generate("RS256");
+    await server.start(0, "localhost");
+    log.debug("Started OAuth server on port %d", server.address().port);
+    return server;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/api_enums.js

@@ -0,0 +1,33 @@
+// Runtime enum-like constants for Neon API string unions.
+//
+// `@neondatabase/api-client` generated TypeScript `enum`s (real runtime objects)
+// for fields like the compute endpoint type. `@neon/sdk` instead models these as
+// plain string-literal union *types*, which have no runtime value — so code that
+// read `EndpointType.ReadWrite` or `Object.values(EndpointType)` no longer works.
+//
+// These `as const` objects restore that runtime surface, and each is paired with
+// a same-named type whose union is identical to the corresponding `@neon/sdk`
+// type, so values stay assignable in both directions.
+export const EndpointType = {
+    ReadOnly: "read_only",
+    ReadWrite: "read_write",
+};
+export const NeonAuthOauthProviderId = {
+    Google: "google",
+    Github: "github",
+    Microsoft: "microsoft",
+    Vercel: "vercel",
+};
+export const NeonAuthOauthProviderType = {
+    Standard: "standard",
+    Shared: "shared",
+};
+export const NeonAuthSupportedAuthProvider = {
+    Mock: "mock",
+    Stack: "stack",
+    BetterAuth: "better_auth",
+};
+export const NeonAuthEmailVerificationMethod = {
+    Link: "link",
+    Otp: "otp",
+};

package/dist/utils/auth.js

@@ -0,0 +1,5 @@
+export const extendTokenSet = (tokenSet) => {
+    const exp = new Date();
+    exp.setSeconds(exp.getSeconds() + (tokenSet.expires_in ?? 0));
+    return { ...tokenSet, expires_at: exp.getTime() };
+};

package/dist/utils/branch_notice.js

@@ -0,0 +1,22 @@
+import chalk from "chalk";
+import { log } from "../log.js";
+/**
+ * Print a one-line "this command is targeting <branch>" notice to **stderr** so
+ * the user can sanity-check they're acting on the branch they think they are —
+ * before a `status` / `plan` / `apply` / `env pull` does its work. This is the
+ * cheap guardrail that catches "I planned against the wrong branch" / "I pulled
+ * env from the wrong branch" before it bites.
+ *
+ * - Skipped for machine-readable output (`--output json|yaml`) so it never has
+ *   to be reasoned about by a script; it's stderr-only regardless, keeping
+ *   `--output table` stdout clean for piping too.
+ * - `verb` is the leading phrase, e.g. `'Planning against branch'` →
+ *   `→ Planning against branch main (br-…)`.
+ */
+export const announceTargetBranch = (props, branch, verb) => {
+    if (props.output === "json" || props.output === "yaml") {
+        return;
+    }
+    const suffix = branch.usedDefault ? chalk.dim(" · project default") : "";
+    log.info("%s %s %s %s%s", chalk.dim("→"), verb, chalk.cyan.bold(branch.branchName), chalk.dim(`(${branch.branchId})`), suffix);
+};

package/dist/utils/branch_picker.js

@@ -0,0 +1,103 @@
+import prompts from "prompts";
+import { retryOnLock } from "../api.js";
+import { isCi } from "../env.js";
+import { log } from "../log.js";
+import { EndpointType } from "./api_enums.js";
+/** Sentinel `value` for the "create a new branch" choice (no branch id can collide). */
+const CREATE_BRANCH_CHOICE = Symbol("create-branch");
+/**
+ * Render a branch's display name with the same word labels as `neonctl branch list`
+ * (`[default]`, `[protected]`) instead of symbols, so the picker reads clearly.
+ */
+const branchLabel = (branch) => {
+    const labels = [];
+    if (branch.default) {
+        labels.push("[default]");
+    }
+    if (branch.protected) {
+        labels.push("[protected]");
+    }
+    labels.push(branch.name);
+    return labels.join(" ");
+};
+/**
+ * Prompt the user to pick a branch from `branches`, with a "＋ Create a new branch…" option
+ * pinned to the top (mirroring the project/org pickers). The default selection is the
+ * project's default branch (the create option sits at index 0, so the default index is
+ * offset by one).
+ *
+ * Throws `opts.nonInteractiveMessage` when there is no TTY (or in CI): the caller knows the
+ * right guidance for its command, so the message is supplied rather than hard-coded here.
+ */
+export const pickBranchInteractively = async (branches, opts) => {
+    if (isCi() || !process.stdout.isTTY) {
+        throw new Error(opts.nonInteractiveMessage);
+    }
+    const defaultBranchIndex = branches.findIndex((b) => b.default);
+    const initial = defaultBranchIndex >= 0 ? defaultBranchIndex + 1 : 0;
+    const { choice } = await prompts({
+        type: "select",
+        name: "choice",
+        message: opts.message,
+        choices: [
+            { title: "＋ Create a new branch…", value: CREATE_BRANCH_CHOICE },
+            ...branches.map((b) => ({
+                title: `${branchLabel(b)} (${b.id})`,
+                value: b.id,
+            })),
+        ],
+        initial,
+    });
+    if (choice === undefined) {
+        throw new Error("Aborted: no branch selected.");
+    }
+    if (choice === CREATE_BRANCH_CHOICE) {
+        return { kind: "create", name: await promptNewBranchName(branches) };
+    }
+    return { kind: "existing", branchId: choice };
+};
+/**
+ * Prompt for a new branch name, rejecting empty input and names already taken on the
+ * project (so we never silently select a different, pre-existing branch).
+ */
+export const promptNewBranchName = async (branches) => {
+    const existing = new Set(branches.map((b) => b.name));
+    const { name } = await prompts({
+        type: "text",
+        name: "name",
+        message: "New branch name:",
+        validate: (value) => {
+            const trimmed = value.trim();
+            if (trimmed === "")
+                return "Branch name cannot be empty.";
+            if (existing.has(trimmed))
+                return `A branch named "${trimmed}" already exists.`;
+            return true;
+        },
+    });
+    const trimmed = typeof name === "string" ? name.trim() : "";
+    if (trimmed === "") {
+        throw new Error("Aborted: no branch name provided.");
+    }
+    return trimmed;
+};
+/**
+ * Create a branch with the same defaults as `neonctl branch create --name <name>`:
+ * branched from the project's default branch with a read-write compute endpoint. Returns
+ * the new branch id.
+ */
+export const createBranch = async (apiClient, projectId, name, branches) => {
+    const defaultBranch = branches.find((b) => b.default);
+    if (!defaultBranch) {
+        throw new Error("No default branch found");
+    }
+    const { data } = await retryOnLock(() => apiClient.createProjectBranch(projectId, {
+        branch: { name, parent_id: defaultBranch.id },
+        endpoints: [{ type: EndpointType.ReadWrite }],
+    }));
+    if (defaultBranch.protected) {
+        log.warning("The parent branch is protected; a unique role password has been generated for the new branch.");
+    }
+    log.info("Created branch %s (%s).", data.branch.name, data.branch.id);
+    return data.branch.id;
+};

package/dist/utils/compute_units.js

@@ -0,0 +1,28 @@
+export const getComputeUnits = (autoscaling) => {
+    const fixedSizeAutoscaling = Number(autoscaling);
+    if (!isNaN(fixedSizeAutoscaling)) {
+        return {
+            autoscaling_limit_min_cu: fixedSizeAutoscaling,
+            autoscaling_limit_max_cu: fixedSizeAutoscaling,
+        };
+    }
+    if (!autoscaling.includes("-")) {
+        throw new Error('Autoscaling should be either fixed size (e.g. 2) or min and max sizes delimited with a dash (e.g. "0.5-1")');
+    }
+    const [min, max] = autoscaling.split("-");
+    if (!min || !max) {
+        throw new Error('Autoscaling should be either fixed size (e.g. 2) or min and max sizes delimited with a dash (e.g. "0.5-1")');
+    }
+    const minAutoscaling = Number(min);
+    const maxAutoscaling = Number(max);
+    if (isNaN(minAutoscaling)) {
+        throw new Error("Autoscaling min should be a number");
+    }
+    if (isNaN(maxAutoscaling)) {
+        throw new Error("Autoscaling max should be a number");
+    }
+    return {
+        autoscaling_limit_min_cu: minAutoscaling,
+        autoscaling_limit_max_cu: maxAutoscaling,
+    };
+};

package/dist/utils/enrichers.js

@@ -0,0 +1,161 @@
+import { isNeonApiError, messageFromBody } from "../api.js";
+import { isConfigInit, isCurrentBranchProbe } from "../context.js";
+import { looksLikeBranchId } from "./formats.js";
+export const branchIdResolve = async ({ branch, apiClient, projectId, }) => {
+    branch = branch.toString();
+    if (looksLikeBranchId(branch)) {
+        return branch;
+    }
+    const { data } = await apiClient.listProjectBranches({
+        projectId,
+    });
+    const branchData = data.branches.find((b) => b.name === branch);
+    if (!branchData) {
+        throw new Error(`Branch ${branch} not found.\nAvailable branches: ${data.branches
+            .map((b) => b.name)
+            .join(", ")}`);
+    }
+    return branchData.id;
+};
+const getBranchIdFromProps = async (props) => {
+    const branch = "branch" in props && typeof props.branch === "string"
+        ? props.branch
+        : props.id;
+    if (branch) {
+        return await branchIdResolve({
+            branch,
+            apiClient: props.apiClient,
+            projectId: props.projectId,
+        });
+    }
+    const { data } = await props.apiClient.listProjectBranches({
+        projectId: props.projectId,
+    });
+    const defaultBranch = data.branches.find((b) => b.default);
+    if (defaultBranch) {
+        return defaultBranch.id;
+    }
+    throw new Error("No default branch found");
+};
+export const branchIdFromProps = async (props) => {
+    props.branchId = await getBranchIdFromProps(props);
+    return props.branchId;
+};
+export const resolveBranchRef = async (props) => {
+    const branch = "branch" in props && typeof props.branch === "string"
+        ? props.branch
+        : props.id;
+    const { data } = await props.apiClient.listProjectBranches({
+        projectId: props.projectId,
+    });
+    const branches = data.branches;
+    if (branch) {
+        const ref = branch.toString();
+        const found = looksLikeBranchId(ref)
+            ? branches.find((b) => b.id === ref)
+            : branches.find((b) => b.name === ref);
+        if (found) {
+            return {
+                branchId: found.id,
+                branchName: found.name ?? found.id,
+                usedDefault: false,
+            };
+        }
+        // A `br-…` id absent from the listing is still usable as an id (trust it like
+        // branchIdResolve does); only an unresolved *name* is a genuine error.
+        if (looksLikeBranchId(ref)) {
+            return { branchId: ref, branchName: ref, usedDefault: false };
+        }
+        throw new Error(`Branch ${ref} not found.\nAvailable branches: ${branches
+            .map((b) => b.name)
+            .join(", ")}`);
+    }
+    const defaultBranch = branches.find((b) => b.default);
+    if (!defaultBranch) {
+        throw new Error("No default branch found");
+    }
+    return {
+        branchId: defaultBranch.id,
+        branchName: defaultBranch.name ?? defaultBranch.id,
+        usedDefault: true,
+    };
+};
+export const resolveSingleDatabase = async (props) => {
+    const { data } = await props.apiClient.listProjectBranchDatabases(props.projectId, props.branchId);
+    const databases = data.databases;
+    if (props.database !== undefined) {
+        if (!databases.find((d) => d.name === props.database)) {
+            throw new Error(`Database not found: ${props.database}. Available databases on branch ${props.branchId}: ${databases.map((d) => d.name).join(", ")}`);
+        }
+        return props.database;
+    }
+    if (databases.length === 0) {
+        throw new Error(`No databases found for the branch: ${props.branchId}`);
+    }
+    if (databases.length === 1) {
+        return databases[0].name;
+    }
+    throw new Error(`Multiple databases found for the branch, please provide one with the --database option: ${databases.map((d) => d.name).join(", ")}`);
+};
+export const fillSingleProject = async (props) => {
+    // The offline `--current-branch` probe needs no project at all and runs with no
+    // API client (auth was skipped), so resolving a single project here would both
+    // hit the network and dereference a null client. Skip it entirely.
+    if (isCurrentBranchProbe(props)) {
+        return props;
+    }
+    // `config init` is purely local (scaffold + npm install) and runs with no API
+    // client, so resolving a single project here would dereference a null client.
+    if (isConfigInit(props)) {
+        return props;
+    }
+    if (props.projectId) {
+        return { ...props, projectId: props.projectId };
+    }
+    // If no orgId is provided, try to auto-fill it if there's only one org
+    let orgId = props.orgId;
+    if (!orgId) {
+        const { data: orgsData } = await props.apiClient.getCurrentUserOrganizations();
+        if (orgsData.organizations.length === 1) {
+            orgId = orgsData.organizations[0].id;
+        }
+    }
+    try {
+        const { data } = await props.apiClient.listProjects({
+            limit: 2,
+            org_id: orgId,
+        });
+        if (data.projects.length === 0) {
+            throw new Error("No projects found");
+        }
+        if (data.projects.length > 1) {
+            throw new Error(`Multiple projects found, please provide one with the --project-id option`);
+        }
+        return {
+            ...props,
+            projectId: data.projects[0].id,
+        };
+    }
+    catch (error) {
+        // If the API error is about missing org_id, provide a user-friendly message
+        if (isNeonApiError(error) &&
+            error.status === 400 &&
+            messageFromBody(error.data)?.includes("org_id is required")) {
+            throw new Error("Multiple projects found, please provide one with the --project-id option");
+        }
+        throw error;
+    }
+};
+export const fillSingleOrg = async (props) => {
+    if (props.orgId) {
+        return props;
+    }
+    const { data } = await props.apiClient.getCurrentUserOrganizations();
+    if (data.organizations.length === 0) {
+        throw new Error("No organizations found");
+    }
+    if (data.organizations.length > 1) {
+        throw new Error(`Multiple organizations found, please provide one with the --org-id option`);
+    }
+    return { ...props, orgId: data.organizations[0].id };
+};