neonctl 2.21.2 → 2.22.2

package/README.md

@@ -62,21 +62,157 @@ For information about obtaining an Neon API key, see [Authentication](https://ap
 
 The Neon CLI supports autocompletion, which you can configure in a few easy steps. See [Neon CLI commands — completion](https://neon.tech/docs/reference/cli-completion) for instructions.
 
+## Linking a project
+
+`neonctl link` is a Vercel-style command that binds the current directory to a Neon project. It picks (or creates) an organization, picks (or creates) a project, resolves the project's default branch, and writes a `.neon` file with `{ "orgId", "projectId", "branchId" }`. Subsequent commands run in this directory (or any sub-directory) automatically pick up that context.
+
+There are three modes:
+
+**Interactive (default)** — guided prompts for humans:
+
+```bash
+$ neonctl link
+? Which organization would you like to link? › Personal Org (org-abc123)
+? Which project would you like to link? › + Create new project
+? Name for the new project: › my-app
+? Which region should the new project run in? › AWS US East (Ohio) (aws-us-east-2)
+Created project polished-snowflake-12345678 ("my-app") in aws-us-east-2.
+Linked .neon:
+  orgId:    org-abc123
+  projectId: polished-snowflake-12345678
+  branchId:  br-main-branch-87654321
+```
+
+**Non-interactive (flags or `--params` JSON)** — for scripts and CI:
+
+```bash
+# Link to an existing project
+neonctl link --org-id org-abc123 --project-id polished-snowflake-12345678
+
+# Create a new project and link
+neonctl link --org-id org-abc123 --project-name my-app --region-id aws-us-east-2
+
+# Same payload, one JSON blob
+neonctl link --params '{"orgId":"org-abc123","projectName":"my-app","regionId":"aws-us-east-2"}'
+```
+
+**Agent mode (`--agent`)** — a JSON state machine designed for AI coding assistants. Each invocation returns a single JSON object with a `status` discriminator describing the next step, the available options, and the exact follow-up command to run.
+
+```bash
+$ neonctl link --agent
+{
+  "status": "needs_org",
+  "instruction": "Ask the user which of these 2 organizations they want to link the current directory to. After they pick one, re-run the next_command_template with the chosen --org-id value.",
+  "options": [
+    { "id": "org-abc123", "name": "Personal Org" },
+    { "id": "org-team",   "name": "Team Org" }
+  ],
+  "next_command_template": "neonctl link --agent --org-id <org_id>"
+}
+
+$ neonctl link --agent --org-id org-abc123
+{
+  "status": "needs_project",
+  "instruction": "Ask the user whether to link to one of these 1 existing projects (use next_command_template with --project-id) or create a new project (use create_option.next_command_template).",
+  "options": [
+    { "id": "polished-snowflake-12345678", "name": "my-app" }
+  ],
+  "create_option": {
+    "instruction": "To create a new project, ask the user for a project name. The region can be omitted to receive a follow-up needs_project_details response that lists available regions.",
+    "next_command_template": "neonctl link --agent --org-id org-abc123 --project-name <name> --region-id <region_id>"
+  },
+  "next_command_template": "neonctl link --agent --org-id org-abc123 --project-id <project_id>"
+}
+
+$ neonctl link --agent --org-id org-abc123 --project-id polished-snowflake-12345678
+{
+  "status": "linked",
+  "context_file": "/path/to/cwd/.neon",
+  "context": {
+    "orgId": "org-abc123",
+    "projectId": "polished-snowflake-12345678",
+    "branchId": "br-main-branch-87654321"
+  },
+  "project": { "id": "polished-snowflake-12345678" },
+  "message": "Linked /path/to/cwd/.neon to project polished-snowflake-12345678 (org org-abc123) on branch br-main-branch-87654321."
+}
+```
+
+The agent flow also handles project creation. If the agent sends `--project-name` without `--region-id`, the next response is `needs_project_details` with the list of supported regions.
+
+**Organization-scoped API keys** (those created at the organization level rather than the user level) cannot list user organizations or call the regions endpoint. `link` handles this transparently:
+
+- If the API key is org-scoped and at least one project already exists in the org, the CLI auto-detects the `org_id` from the first project. In interactive mode it prints an informational message; in `--agent` mode it skips straight to `needs_project`.
+- If the API key is org-scoped and no projects exist yet, `--agent` returns a `needs_org` response with `options: []` and an instruction telling the user to find their org ID in the Neon Console. Interactive mode prints an error pointing to `--org-id`.
+- When the regions endpoint is not allowed, `link` falls back to a built-in static region list.
+
+**Agent error contract**: any unexpected failure in `--agent` mode is reported as JSON to stdout with exit code 1, so agents can always parse the response:
+
+```json
+{
+  "status": "error",
+  "code": "CLIENT_ERROR",
+  "message": "user has no access to projects"
+}
+```
+
+`link` is a thin wrapper around `set-context`: both write to the same `.neon` file via a shared `applyContext` helper, so anything `link` can write, `set-context` can write too (including the newly-supported `--branch-id` flag).
+
+### checkout
+
+`checkout [id|name]` pins a branch in the local context so subsequent commands target it — it's a focused helper over `set-context` for the common "switch the branch I'm working on" case. It resolves the branch (by name or id) against the project, then **heals** the `.neon` file: it always (re)writes `projectId`, `branchId`, and `orgId` (when the project has one), so a `.neon` that was missing fields or drifted ends up complete and consistent. When `orgId` isn't already known (from `--org-id` or the existing `.neon`), it's looked up from the project itself.
+
+The branch argument is **optional**: run `neonctl checkout` with no branch in an interactive terminal to fetch the project's branches and pick one from a list. In a non-interactive context (CI or no TTY), a branch must be passed explicitly.
+
+Branch **id vs name** is detected automatically (a `br-…` value is treated as an id):
+
+- **id** — matched strictly by id. A non-existent id is a hard "not found" error (ids are server-assigned, so checkout never creates one).
+- **name** — matched by name. If the name doesn't exist, in an interactive terminal `checkout` offers to **create** it (equivalent to `neonctl branch create --name <name>`: branched from the project's default branch with a read-write compute), then checks it out. In a non-interactive context a missing name is the usual "not found" error.
+
+The project is resolved through the standard neonctl chain, each entry winning over the next:
+
+1. `--project-id <id>` flag
+2. `projectId` from the closest `.neon` file (found by walking up from the current directory — see "Where `.neon` lives" below)
+3. If still unresolved and the API key maps to exactly one project, that project is auto-detected (same behaviour as `branches` and `connection-string`)
+
+If none of those resolve a project, `checkout` prints a telling error explaining the chain above. In an interactive terminal it then offers to run `neonctl link` in the current folder so you can pick (or create) a project on the spot; once linked, it continues and pins the requested branch. In non-interactive contexts (CI or no TTY) it exits with a non-zero code and the same guidance instead of prompting.
+
+The resolved branch id is then written to the same `.neon` file that `link` and `set-context` use:
+
+```bash
+$ neonctl checkout main --project-id polished-snowflake-12345678
+INFO: Checked out branch br-main-branch-87654321 on project polished-snowflake-12345678. Updated /path/to/cwd/.neon.
+
+$ cat .neon
+{
+  "orgId": "org-abc123",
+  "projectId": "polished-snowflake-12345678",
+  "branchId": "br-main-branch-87654321"
+}
+```
+
+**Where `.neon` lives**: `link` (and `set-context`) write `.neon` into the **current working directory** by default. If an existing `.neon` is found in any parent directory, that file is reused — so commands run from a sub-directory of a linked project still pick up the project's context. To pin the location explicitly, pass `--context-file <path>`.
+
+**`.gitignore` scaffolding**: when `.neon` is **created** for the first time, the CLI also makes sure a `.gitignore` sits alongside it listing `.neon`. If `.gitignore` doesn't exist it's created with a single `.neon` line; if it does exist, `.neon` is appended only when missing (no duplicates, your other entries are left alone). On subsequent updates to an existing `.neon`, `.gitignore` is left untouched — so if you deliberately un-ignore `.neon` (e.g. to commit shared context), the entry is not re-added on every command.
+
 ## Commands
 
-| Command                                                                    | Subcommands                                                                                 | Description                  |
-| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------- |
-| [auth](https://neon.com/docs/reference/cli-auth)                           |                                                                                             | Authenticate                 |
-| [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              |
-| [me](https://neon.com/docs/reference/cli-me)                               |                                                                                             | Show current user            |
-| [branches](https://neon.com/docs/reference/cli-branches)                   | `list`, `create`, `rename`, `add-compute`, `set-default`, `set-expiration`, `delete`, `get` | Manage branches              |
-| [databases](https://neon.com/docs/reference/cli-databases)                 | `list`, `create`, `delete`                                                                  | Manage databases             |
-| [roles](https://neon.com/docs/reference/cli-roles)                         | `list`, `create`, `delete`                                                                  | Manage roles                 |
-| [operations](https://neon.com/docs/reference/cli-operations)               | `list`                                                                                      | Manage operations            |
-| [connection-string](https://neon.com/docs/reference/cli-connection-string) |                                                                                             | Get connection string        |
-| [set-context](https://neon.com/docs/reference/cli-set-context)             |                                                                                             | Set context for session      |
-| [completion](https://neon.com/docs/reference/cli-completion)               |                                                                                             | Generate a completion script |
+| Command                                                                    | Subcommands                                                                                 | Description                    |
+| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------ |
+| [auth](https://neon.com/docs/reference/cli-auth)                           |                                                                                             | Authenticate                   |
+| [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                |
+| [me](https://neon.com/docs/reference/cli-me)                               |                                                                                             | Show current user              |
+| [branches](https://neon.com/docs/reference/cli-branches)                   | `list`, `create`, `rename`, `add-compute`, `set-default`, `set-expiration`, `delete`, `get` | Manage branches                |
+| [databases](https://neon.com/docs/reference/cli-databases)                 | `list`, `create`, `delete`                                                                  | Manage databases               |
+| [roles](https://neon.com/docs/reference/cli-roles)                         | `list`, `create`, `delete`                                                                  | Manage roles                   |
+| [operations](https://neon.com/docs/reference/cli-operations)               | `list`                                                                                      | Manage operations              |
+| [connection-string](https://neon.com/docs/reference/cli-connection-string) |                                                                                             | Get connection string          |
+| psql                                                                       |                                                                                             | Connect to a database via psql |
+| [set-context](https://neon.com/docs/reference/cli-set-context)             |                                                                                             | Set context for session        |
+| checkout                                                                   |                                                                                             | Pin a branch in `.neon`        |
+| [link](https://neon.com/docs/reference/cli-link)                           |                                                                                             | Link a directory to a project  |
+| [completion](https://neon.com/docs/reference/cli-completion)               |                                                                                             | Generate a completion script   |
 
 ## Global options
 
@@ -142,17 +278,19 @@ Global options are supported with any Neon CLI command.
 
 ## Contribute
 
+This repo uses [pnpm](https://pnpm.io). The required version is pinned in `.tool-versions` and `package.json`'s `packageManager` field. The simplest way to get the right version is [mise](https://mise.jdx.dev): `mise install` reads `.tool-versions` and installs Node and pnpm. Alternatives: `npm install -g pnpm@9.15.9`, or [Corepack](https://nodejs.org/api/corepack.html) (`corepack enable pnpm`).
+
 To run the CLI locally, execute the build command after making changes:
 
 ```shell
-bun install
-bun run build
+pnpm install
+pnpm run build
 ```
 
 To develop continuously:
 
 ```shell
-bun run watch
+pnpm run watch
 ```
 
 To run commands from the local build, replace the `neonctl` command with `node dist`; for example:
@@ -160,3 +298,7 @@ To run commands from the local build, replace the `neonctl` command with `node d
 ```shell
 node dist branches --help
 ```
+
+## Releasing
+
+Maintainers: see [`RELEASING.md`](./RELEASING.md) for the two-stage publish flow.

package/commands/checkout.js

@@ -0,0 +1,249 @@
+import { EndpointType } from '@neondatabase/api-client';
+import { isAxiosError } from 'axios';
+import prompts from 'prompts';
+import { retryOnLock } from '../api.js';
+import { applyContext, readContextFile } from '../context.js';
+import { isCi } from '../env.js';
+import { log } from '../log.js';
+import { fillSingleProject } from '../utils/enrichers.js';
+import { looksLikeBranchId } from '../utils/formats.js';
+import { handler as linkHandler } from './link.js';
+// The positional is optional: omitting it in an interactive terminal opens a
+// branch picker. In non-interactive contexts a missing branch is an error.
+export const command = 'checkout [id|name]';
+export const describe = 'Pin a branch in the local context (.neon) so subsequent commands target it';
+export const builder = (argv) => argv
+    .usage('$0 checkout [id|name] [options]')
+    .positional('id', {
+    describe: 'Branch name or id to check out. Omit to pick interactively from the list of branches.',
+    type: 'string',
+})
+    .options({
+    'project-id': {
+        describe: 'Project ID',
+        type: 'string',
+    },
+})
+    .example([
+    [
+        '$0 checkout',
+        'Pick a branch interactively from the project in the closest .neon file',
+    ],
+    [
+        '$0 checkout main',
+        'Pin the branch named "main" in the closest .neon file',
+    ],
+    [
+        '$0 checkout br-cool-snow-12345678 --project-id project-id-123',
+        'Pin a branch by id for an explicit project',
+    ],
+]);
+export const handler = async (props) => {
+    // Branch listing is project-scoped, so `projectId` is the only thing
+    // `checkout` actually needs. Resolve it through the standard chain
+    // (--project-id flag > .neon file > single-project auto-detect); when
+    // nothing resolves, fall back to an interactive `neonctl link`.
+    const projectId = await resolveProjectId(props);
+    const branchId = await resolveBranchId(props, projectId);
+    const orgId = await resolveOrgId(props, projectId);
+    // `checkout` is a thin helper over `set-context`. It fully "heals" the
+    // context file: it always (re)writes `projectId`, `branchId`, and `orgId`
+    // (when the project has one) so a `.neon` that drifted or was missing fields
+    // ends up complete and consistent after checkout.
+    applyContext(props.contextFile, {
+        projectId,
+        ...(orgId ? { orgId } : {}),
+        branchId,
+    });
+    log.info('Checked out branch %s on project %s%s. Updated %s.', branchId, projectId, orgId ? ` (org ${orgId})` : '', props.contextFile);
+};
+/**
+ * Resolve the branch id to check out.
+ *
+ * - Branch **id** (`br-…`): looked up by id. A non-existent id is a hard "not
+ *   found" error — we never offer to create one, since ids are server-assigned.
+ * - Branch **name**: looked up by name. If it doesn't exist, in an interactive
+ *   terminal we offer to create it (like `neonctl branch create --name <name>`);
+ *   in a non-interactive context it's the usual "not found" error.
+ * - **Omitted**: open an interactive picker listing the project's branches (TTY
+ *   only); in a non-interactive context a missing branch is a hard error.
+ */
+const resolveBranchId = async (props, projectId) => {
+    const branches = (await props.apiClient.listProjectBranches({ projectId }))
+        .data.branches;
+    if (!props.id) {
+        return pickBranchInteractively(branches, projectId);
+    }
+    const ref = props.id;
+    // A `br-…` value is an id; match strictly by id and never offer to create.
+    if (looksLikeBranchId(ref)) {
+        const byId = branches.find((b) => b.id === ref);
+        if (byId) {
+            return byId.id;
+        }
+        throw new Error(notFoundMessage(ref, branches));
+    }
+    const byName = branches.find((b) => b.name === ref);
+    if (byName) {
+        return byName.id;
+    }
+    // Name not found: offer to create it interactively, mirroring `branch create`.
+    if (isCi() || !process.stdout.isTTY) {
+        throw new Error(notFoundMessage(ref, branches));
+    }
+    log.error(notFoundMessage(ref, branches));
+    const { create } = await prompts({
+        type: 'confirm',
+        name: 'create',
+        message: `Branch "${ref}" does not exist. Create it now?`,
+        initial: true,
+    });
+    if (!create) {
+        throw new Error(`Aborted: branch "${ref}" was not found and not created.`);
+    }
+    return createBranch(props, projectId, ref, branches);
+};
+const notFoundMessage = (ref, branches) => `Branch ${ref} not found.\nAvailable branches: ${branches
+    .map((b) => b.name)
+    .join(', ')}`;
+const pickBranchInteractively = async (branches, projectId) => {
+    if (isCi() || !process.stdout.isTTY) {
+        throw new Error('No branch specified. Pass a branch name or id (e.g. `neonctl checkout main`), ' +
+            'or run interactively to pick one from a list.');
+    }
+    if (branches.length === 0) {
+        throw new Error(`No branches found for project ${projectId}.`);
+    }
+    const defaultIndex = Math.max(0, branches.findIndex((b) => b.default));
+    const { branchId } = await prompts({
+        type: 'select',
+        name: 'branchId',
+        message: 'Which branch would you like to check out?',
+        choices: branches.map((b) => ({
+            title: `${b.default ? '✱ ' : ''}${b.name} (${b.id})`,
+            value: b.id,
+        })),
+        initial: defaultIndex,
+    });
+    if (!branchId) {
+        throw new Error('Aborted: no branch selected.');
+    }
+    return branchId;
+};
+/**
+ * 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.
+ */
+const createBranch = async (props, projectId, name, branches) => {
+    const defaultBranch = branches.find((b) => b.default);
+    if (!defaultBranch) {
+        throw new Error('No default branch found');
+    }
+    const { data } = await retryOnLock(() => props.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;
+};
+/**
+ * Resolve the org id to heal into the context file.
+ *
+ * Prefer an org id we already know (from `--org-id`, the `.neon` file, or a
+ * freshly-run `link`). Otherwise look it up from the project itself so the
+ * `.neon` file ends up with an accurate `orgId` even when it was previously
+ * missing. Projects on a personal account have no org; in that case (or if the
+ * lookup fails for a non-auth reason) we return `undefined` and simply omit the
+ * field rather than failing the checkout.
+ */
+const resolveOrgId = async (props, projectId) => {
+    if (props.orgId) {
+        return props.orgId;
+    }
+    try {
+        const { data } = await props.apiClient.getProject(projectId);
+        return data.project.org_id ?? undefined;
+    }
+    catch (err) {
+        if (isAxiosError(err) && err.response?.status === 401) {
+            throw err;
+        }
+        log.debug('checkout: could not resolve org id for project %s: %s', projectId, err instanceof Error ? err.message : String(err));
+        return undefined;
+    }
+};
+/**
+ * Resolve the project id `checkout` should target.
+ *
+ * `props.projectId` is already populated from the `--project-id` flag or the
+ * closest `.neon` file (via the global `enrichFromContext` middleware). When
+ * it's still missing we try to auto-detect a single project (same behaviour as
+ * `branches` / `connection-string`). If that fails we surface a telling error
+ * and, in an interactive terminal, offer to run `neonctl link` in the current
+ * folder so the user can pick a project/branch without having to re-run the
+ * command by hand.
+ */
+const resolveProjectId = async (props) => {
+    if (props.projectId) {
+        return props.projectId;
+    }
+    const autoDetected = await tryAutoDetectProject(props);
+    if (autoDetected) {
+        return autoDetected;
+    }
+    const missingProjectMessage = 'Could not determine which Neon project to check out a branch from. ' +
+        'Provide one via the --project-id flag ' +
+        'or a .neon file (created by `neonctl link` / `neonctl set-context`).';
+    if (isCi() || !process.stdout.isTTY) {
+        throw new Error(missingProjectMessage);
+    }
+    log.error(missingProjectMessage);
+    const { runLink } = await prompts({
+        type: 'confirm',
+        name: 'runLink',
+        message: 'Run `neonctl link` in the current folder to pick a project now?',
+        initial: true,
+    });
+    if (!runLink) {
+        throw new Error('Aborted: no project selected. Re-run with --project-id or link a project first.');
+    }
+    await linkHandler({
+        ...props,
+        agent: false,
+        yes: false,
+    });
+    const linked = readContextFile(props.contextFile);
+    if (!linked.projectId) {
+        throw new Error('Linking did not produce a project id. Re-run `neonctl checkout` once the directory is linked.');
+    }
+    // Carry the freshly-linked org id forward so the merge below keeps it.
+    if (linked.orgId) {
+        props.orgId = linked.orgId;
+    }
+    return linked.projectId;
+};
+/**
+ * Best-effort single-project auto-detection. Returns the project id when the
+ * API key maps to exactly one project, or `undefined` when the project can't be
+ * determined unambiguously (zero or multiple projects) so the caller can fall
+ * back to the interactive `link` flow.
+ */
+const tryAutoDetectProject = async (props) => {
+    try {
+        const filled = await fillSingleProject(props);
+        return filled.projectId;
+    }
+    catch (err) {
+        // `fillSingleProject` throws on "No projects found" / "Multiple projects
+        // found" — both mean we can't pick a project automatically. Network/auth
+        // errors are real and should surface to the user.
+        if (isAxiosError(err)) {
+            throw err;
+        }
+        log.debug('checkout: could not auto-detect a single project: %s', err instanceof Error ? err.message : String(err));
+        return undefined;
+    }
+};

package/commands/checkout.test.js

@@ -0,0 +1,170 @@
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect } from 'vitest';
+import { test as originalTest } from '../test_utils/fixtures';
+// All tests in this file share a single temporary directory whose path is
+// normalized in snapshots to `<TMP>` so absolute paths in command output stay
+// stable across runs and machines.
+const TEST_TMP = mkdtempSync(join(tmpdir(), 'neonctl-checkout-'));
+const test = originalTest.extend({
+    // eslint-disable-next-line no-empty-pattern
+    readFile: async ({}, use) => {
+        await use((name) => readFileSync(name, 'utf-8'));
+    },
+    // eslint-disable-next-line no-empty-pattern
+    removeFile: async ({}, use) => {
+        await use((name) => {
+            try {
+                rmSync(name);
+            }
+            catch {
+                // ignore
+            }
+        });
+    },
+    // eslint-disable-next-line no-empty-pattern
+    tmpContext: async ({}, use) => {
+        await use((label, seed) => {
+            const dir = join(TEST_TMP, label);
+            mkdirSync(dir, { recursive: true });
+            const ctx = join(dir, '.neon');
+            if (seed) {
+                writeFileSync(ctx, JSON.stringify(seed, null, 2));
+            }
+            return ctx;
+        });
+    },
+});
+const parseContext = (raw) => JSON.parse(raw);
+describe('checkout', () => {
+    test('resolves a branch by name and writes branchId to a fresh .neon', async ({ testCliCommand, readFile, tmpContext, }) => {
+        const ctx = tmpContext('by_name_fresh');
+        await testCliCommand([
+            'checkout',
+            'main',
+            '--project-id',
+            'test',
+            '--context-file',
+            ctx,
+        ]);
+        expect(parseContext(readFile(ctx))).toEqual({
+            projectId: 'test',
+            branchId: 'br-main-branch-123456',
+        });
+    });
+    test('resolves a branch by id and writes branchId to a fresh .neon', async ({ testCliCommand, readFile, tmpContext, }) => {
+        const ctx = tmpContext('by_id_fresh');
+        await testCliCommand([
+            'checkout',
+            'br-sunny-branch-123456',
+            '--project-id',
+            'test',
+            '--context-file',
+            ctx,
+        ]);
+        expect(parseContext(readFile(ctx))).toEqual({
+            projectId: 'test',
+            branchId: 'br-sunny-branch-123456',
+        });
+    });
+    test('preserves orgId/projectId already present in the .neon file', async ({ testCliCommand, readFile, tmpContext, }) => {
+        const ctx = tmpContext('preserve_org', {
+            orgId: 'org-keep',
+            projectId: 'test',
+        });
+        await testCliCommand(['checkout', 'test_branch', '--context-file', ctx]);
+        expect(parseContext(readFile(ctx))).toEqual({
+            orgId: 'org-keep',
+            projectId: 'test',
+            branchId: 'br-sunny-branch-123456',
+        });
+    });
+    test('heals a missing orgId by resolving it from the project', async ({ testCliCommand, readFile, tmpContext, }) => {
+        // The .neon only has projectId; checkout should look up the project's
+        // org_id and write all three fields so the context file ends up complete.
+        const ctx = tmpContext('heal_org', { projectId: 'test' });
+        await testCliCommand(['checkout', 'main', '--context-file', ctx], {
+            mockDir: 'checkout_heal_org',
+        });
+        expect(parseContext(readFile(ctx))).toEqual({
+            orgId: 'org-healed-123',
+            projectId: 'test',
+            branchId: 'br-main-branch-123456',
+        });
+    });
+    test('resolves projectId from the .neon file when no flag is passed', async ({ testCliCommand, readFile, tmpContext, }) => {
+        const ctx = tmpContext('project_from_file', { projectId: 'test' });
+        await testCliCommand(['checkout', 'main', '--context-file', ctx]);
+        expect(parseContext(readFile(ctx))).toEqual({
+            projectId: 'test',
+            branchId: 'br-main-branch-123456',
+        });
+    });
+    test('auto-detects the project when the API key maps to a single project', async ({ testCliCommand, readFile, tmpContext, }) => {
+        // No --project-id and a fresh .neon: checkout should fall
+        // back to single-project auto-detection (same behaviour as branches / cs).
+        const ctx = tmpContext('autodetect_single');
+        await testCliCommand(['checkout', 'main', '--context-file', ctx], {
+            mockDir: 'single_project',
+        });
+        expect(parseContext(readFile(ctx))).toEqual({
+            projectId: 'test-project-123456',
+            branchId: 'br-main-branch-123456',
+        });
+    });
+    test('fails with a telling error when no project can be resolved (non-interactive)', async ({ testCliCommand, removeFile, tmpContext, }) => {
+        // Fresh .neon, no --project-id, and the mock account has no projects so
+        // single-project auto-detection can't pick one. The forked CLI has no TTY,
+        // so we expect the telling error instead of a prompt.
+        const ctx = tmpContext('no_project');
+        await testCliCommand(['checkout', 'main', '--context-file', ctx], {
+            mockDir: 'checkout_no_project',
+            code: 1,
+            stderr: 'ERROR: Could not determine which Neon project to check out a branch from. Provide one via the --project-id flag or a .neon file (created by `neonctl link` / `neonctl set-context`).',
+        });
+        removeFile(ctx);
+    });
+    test('fails with a helpful error when the branch is not found', async ({ testCliCommand, removeFile, tmpContext, }) => {
+        const ctx = tmpContext('not_found');
+        await testCliCommand([
+            'checkout',
+            'does-not-exist',
+            '--project-id',
+            'test',
+            '--context-file',
+            ctx,
+        ], {
+            code: 1,
+            stderr: 'ERROR: Branch does-not-exist not found. Available branches: main, test_branch, 123, test_branch_with_fixed_cu, test_branch_with_autoscaling, protected_branch',
+        });
+        removeFile(ctx);
+    });
+    test('errors when a branch id is not found (ids are never auto-created)', async ({ testCliCommand, removeFile, tmpContext, }) => {
+        // A `br-…` value is treated as an id and matched strictly; a non-existent
+        // id is a hard not-found error (no create offer, even interactively).
+        const ctx = tmpContext('id_not_found');
+        await testCliCommand([
+            'checkout',
+            'br-does-not-exist-123456',
+            '--project-id',
+            'test',
+            '--context-file',
+            ctx,
+        ], {
+            code: 1,
+            stderr: 'ERROR: Branch br-does-not-exist-123456 not found. Available branches: main, test_branch, 123, test_branch_with_fixed_cu, test_branch_with_autoscaling, protected_branch',
+        });
+        removeFile(ctx);
+    });
+    test('errors when no branch is given in a non-interactive context', async ({ testCliCommand, removeFile, tmpContext, }) => {
+        // Project resolves fine (from --project-id), but no branch was passed and
+        // the forked CLI has no TTY, so the interactive picker is not available.
+        const ctx = tmpContext('no_branch');
+        await testCliCommand(['checkout', '--project-id', 'test', '--context-file', ctx], {
+            code: 1,
+            stderr: 'ERROR: No branch specified. Pass a branch name or id (e.g. `neonctl checkout main`), or run interactively to pick one from a list.',
+        });
+        removeFile(ctx);
+    });
+});

package/commands/connection_string.js

@@ -3,7 +3,12 @@ import { branchIdFromProps, fillSingleProject } from '../utils/enrichers.js';
 import { writer } from '../writer.js';
 import { psql } from '../utils/psql.js';
 import { parsePITBranch } from '../utils/point_in_time.js';
-const SSL_MODES = ['require', 'verify-ca', 'verify-full', 'omit'];
+export const SSL_MODES = [
+    'require',
+    'verify-ca',
+    'verify-full',
+    'omit',
+];
 export const command = 'connection-string [branch]';
 export const aliases = ['cs'];
 export const describe = 'Get connection string';