neonctl 2.24.2 → 2.25.1

package/commands/link.js

@@ -1,6 +1,6 @@
 import { isAxiosError } from 'axios';
 import prompts from 'prompts';
-import { applyContext, readContextFile } from '../context.js';
+import { applyContext, contextBranch, readContextFile, setContext, updateContextFile, } from '../context.js';
 import { isCi } from '../env.js';
 import { log } from '../log.js';
 import { createBranch, pickBranchInteractively, } from '../utils/branch_picker.js';
@@ -10,7 +10,9 @@ const PROJECTS_LIST_LIMIT = 100;
 const CREATE_NEW_SENTINEL = '__create_new__';
 export const command = 'link';
 export const describe = 'Link the current directory to a Neon project';
-export const builder = (argv) => argv.usage('$0 link [options]').options({
+export const builder = (argv) => argv
+    .usage('$0 link [options]')
+    .options({
     'org-id': {
         describe: 'Organization ID to link to',
         type: 'string',
@@ -27,6 +29,13 @@ export const builder = (argv) => argv.usage('$0 link [options]').options({
         describe: 'Region ID for a new project (e.g. aws-us-east-2). Required with --project-name.',
         type: 'string',
     },
+    branch: {
+        alias: 'branch-id',
+        describe: 'Branch name or ID to pin in the context (resolved to its ID before writing). ' +
+            'Without it, link only resolves the org and project — pin a branch with ' +
+            '`neonctl checkout <branch>` (link never guesses a default).',
+        type: 'string',
+    },
     params: {
         describe: 'JSON object with link parameters, e.g. \'{"orgId":"...","projectId":"..."}\' or \'{"orgId":"...","projectName":"...","regionId":"..."}\'. Flags take precedence over fields in --params.',
         type: 'string',
@@ -42,23 +51,64 @@ export const builder = (argv) => argv.usage('$0 link [options]').options({
         type: 'boolean',
         default: false,
     },
+    clear: {
+        describe: 'Remove the org/project/branch context (writes an empty context file) instead of linking.',
+        type: 'boolean',
+        default: false,
+    },
+    checks: {
+        describe: 'Verify the org/project/branch exist (and resolve the org from the project) before ' +
+            'writing. On by default; use --no-checks to write the context offline with no API ' +
+            'calls — it then requires --org-id and --project-id (--branch optional) and skips ' +
+            'env pull.',
+        type: 'boolean',
+        default: true,
+    },
     'env-pull': {
         describe: "Pull the linked branch's Neon env vars (DATABASE_URL, …) into a local .env after " +
             'linking. On by default; use --no-env-pull to skip (e.g. when injecting env at ' +
-            'runtime with `neon-env run` / `neon dev`).',
+            'runtime with `neon-env run` / `neon dev`). Only runs when a branch is pinned.',
         type: 'boolean',
         default: true,
     },
-});
+})
+    .example([
+    [
+        '$0 link --project-id polished-snowflake-12345678',
+        "Link an existing project (org is inferred); pin a branch later with 'neonctl checkout'",
+    ],
+    [
+        '$0 link --org-id org-… --project-name my-app --region-id aws-us-east-2',
+        'Create a new project and link it',
+    ],
+    [
+        '$0 link --branch-id br-…',
+        'Pin a branch in the already-linked project',
+    ],
+    [
+        '$0 link --no-checks --org-id org-… --project-id polished-snowflake-12345678',
+        'Write the context offline (no API calls, no verification)',
+    ],
+    ['$0 link --clear', 'Forget the current org/project/branch context'],
+]);
 export const handler = async (props) => {
+    if (props.clear) {
+        clearContext(props.contextFile);
+        return;
+    }
+    if (!props.checks) {
+        runWithoutChecks(props);
+        return;
+    }
     if (props.agent) {
         await runAgentSafely(props);
         return;
     }
     const inputs = parseInputs(props);
     validateInputs(inputs);
-    if (hasEnoughForNonInteractive(inputs)) {
-        await runNonInteractive(props, inputs);
+    const existing = readContextFile(props.contextFile);
+    if (canResolveNonInteractively(inputs, existing)) {
+        await runNonInteractive(props, inputs, existing);
         return;
     }
     if (isCi()) {
@@ -67,7 +117,7 @@ export const handler = async (props) => {
             '',
             'Use one of:',
             '  neonctl link --agent                                                    (JSON state machine for agents)',
-            '  neonctl link --org-id <org> --project-id <project>                      (link to an existing project)',
+            '  neonctl link --project-id <project>                                     (link to an existing project; org is inferred)',
             '  neonctl link --org-id <org> --project-name <name> --region-id <region>  (create a new project and link)',
         ].join('\n'));
         process.exit(1);
@@ -96,6 +146,7 @@ const parseInputs = (props) => {
         projectId: props.projectId ?? fromParams.projectId,
         projectName: props.projectName ?? fromParams.projectName,
         regionId: props.regionId ?? fromParams.regionId,
+        branch: props.branch ?? fromParams.branch,
     };
 };
 const extractParams = (raw) => {
@@ -117,60 +168,314 @@ const extractParams = (raw) => {
         projectId: pickString('projectId'),
         projectName: pickString('projectName'),
         regionId: pickString('regionId'),
+        branch: pickString('branch') ?? pickString('branchId'),
     };
 };
 const validateInputs = (inputs) => {
     if (inputs.projectId && (inputs.projectName || inputs.regionId)) {
         throw new Error('Conflicting inputs: --project-id selects an existing project; --project-name and --region-id describe a new one. Pass only one set.');
     }
+    if (inputs.projectName && inputs.branch) {
+        throw new Error('Conflicting inputs: --branch pins a branch of an existing project, but --project-name creates a new one. Create the project first, then `neonctl checkout <branch>`.');
+    }
 };
-const hasEnoughForNonInteractive = (inputs) => {
-    if (inputs.orgId && inputs.projectId)
+/**
+ * Whether the inputs (combined with the existing `.neon`) fully determine what
+ * to write without prompting the user. Everything else falls back to the
+ * interactive picker (TTY) or the CI guard.
+ *
+ * - `--project-id` is always enough: the org is inferred from the project and
+ *   the branch is left to an explicit `checkout` (never auto-defaulted).
+ * - `--org-id --project-name --region-id` fully describes a project to create.
+ * - `--branch-id` needs a project, which it takes from the existing `.neon`.
+ * - `--org-id` on its own just records the default org (merged into any
+ *   existing context).
+ */
+const canResolveNonInteractively = (inputs, existing) => {
+    if (inputs.projectId)
         return true;
     if (inputs.orgId && inputs.projectName && inputs.regionId)
         return true;
+    if (inputs.branch && existing.projectId)
+        return true;
+    if (inputs.orgId && !inputs.projectName && !inputs.branch)
+        return true;
     return false;
 };
 // ----------------------------------------------------------------------------
+// Context helpers
+// ----------------------------------------------------------------------------
+const clearContext = (contextFile) => {
+    updateContextFile(contextFile, {});
+    process.stdout.write(`Cleared ${contextFile}. The directory is no longer linked to a Neon org/project/branch.\n`);
+};
+/**
+ * `--no-checks`: write the context offline. Makes no API calls — so no org
+ * inference, no existence/access verification, and no env pull — which means
+ * the caller must supply both `--org-id` and `--project-id` (the org can't be
+ * inferred without the network). `--branch` stays optional. This is the CLI
+ * surface over {@link setContext}, useful for scripted/offline setups and for
+ * re-creating a `.neon` from values you already trust.
+ */
+const runWithoutChecks = (props) => {
+    const inputs = parseInputs(props);
+    validateInputs(inputs);
+    if (inputs.projectName) {
+        throw new Error("--no-checks can't create a project (that needs API access). Pass --org-id and --project-id for an existing project, or drop --no-checks.");
+    }
+    if (!inputs.orgId || !inputs.projectId) {
+        throw new Error('--no-checks writes the context with no API calls, so it needs both --org-id and --project-id (--branch is optional).');
+    }
+    setContext(props.contextFile, {
+        orgId: inputs.orgId,
+        projectId: inputs.projectId,
+        branch: inputs.branch,
+    });
+    if (props.agent) {
+        emitAgent({
+            status: 'linked',
+            context_file: props.contextFile,
+            context: {
+                orgId: inputs.orgId,
+                projectId: inputs.projectId,
+                branch: inputs.branch,
+            },
+            project: { id: inputs.projectId },
+            message: `Wrote ${props.contextFile} without checks (org ${inputs.orgId}, project ${inputs.projectId}${inputs.branch ? `, branch ${inputs.branch}` : ''}). No verification or env pull was performed.`,
+        });
+        return;
+    }
+    printSummary(props, {
+        contextFile: props.contextFile,
+        orgId: inputs.orgId,
+        projectId: inputs.projectId,
+        branch: inputs.branch,
+        created: false,
+        noChecks: true,
+    });
+};
+/**
+ * A bad user-supplied identifier (project/org/branch that doesn't exist or
+ * isn't accessible). Carries an `agentCode` so `--agent` mode can report a
+ * precise `status: error` code instead of a generic INTERNAL_ERROR, while the
+ * human path just prints the clear `message`.
+ */
+class LinkInputError extends Error {
+    constructor(message, agentCode) {
+        super(message);
+        this.name = 'LinkInputError';
+        this.agentCode = agentCode;
+    }
+}
+const httpStatus = (err) => isAxiosError(err) ? err.response?.status : undefined;
+/**
+ * Fetch a project, turning the common failure modes into clear, actionable
+ * errors. 401 is rethrown so the global handler can refresh credentials;
+ * everything else surfaces as a `LinkInputError` the user (or agent) can act on.
+ */
+const fetchProjectOrThrow = async (props, projectId) => {
+    try {
+        const { data } = await props.apiClient.getProject(projectId);
+        return data.project;
+    }
+    catch (err) {
+        const status = httpStatus(err);
+        if (status === 401) {
+            throw err;
+        }
+        if (status === 403) {
+            throw new LinkInputError(`You don't have access to project '${projectId}'. Check that your API key's account or organization can see it.`, 'NO_ACCESS');
+        }
+        if (status === 404) {
+            throw new LinkInputError(`Project '${projectId}' not found. Double-check the project ID — or that your API key has access to it.`, 'NOT_FOUND');
+        }
+        throw err;
+    }
+};
+/**
+ * Confirm the org exists and is reachable with the current API key by listing
+ * its projects (allowed for both user and org-scoped keys). Maps 403/404 to a
+ * clear message; 401 is rethrown for credential refresh.
+ */
+const verifyOrgAccess = async (props, orgId) => {
+    try {
+        await props.apiClient.listProjects({
+            org_id: orgId,
+            limit: PROJECTS_LIST_LIMIT,
+        });
+    }
+    catch (err) {
+        const status = httpStatus(err);
+        if (status === 401) {
+            throw err;
+        }
+        if (status === 403 || status === 404) {
+            throw new LinkInputError(`Organization '${orgId}' not found, or your API key doesn't have access to it. Find your org ID in the Neon Console under Settings.`, status === 403 ? 'NO_ACCESS' : 'NOT_FOUND');
+        }
+        throw err;
+    }
+};
+/**
+ * Resolve a branch reference (name *or* id) to the matching branch, while
+ * confirming it actually exists in the project. Unlike the shared
+ * `branchIdResolve`, this also verifies references that already look like ids
+ * (so a typo'd `br-…` doesn't silently get written), and surfaces the available
+ * branches when nothing matches so the user can correct it (or run `checkout`).
+ */
+const resolveBranchRef = async (props, projectId, branchRef) => {
+    const { data } = await props.apiClient.listProjectBranches({ projectId });
+    const match = data.branches.find((b) => b.id === branchRef) ??
+        data.branches.find((b) => b.name === branchRef);
+    if (match) {
+        return match;
+    }
+    const available = data.branches.length > 0
+        ? data.branches
+            .map((b) => `${b.id}${b.name ? ` (${b.name})` : ''}`)
+            .join(', ')
+        : '(none)';
+    throw new LinkInputError(`Branch '${branchRef}' not found in project '${projectId}'. Available branches: ${available}. Pin one with \`neonctl checkout <branch>\`.`, 'NOT_FOUND');
+};
+/**
+ * The value to persist for a branch: prefer its human-readable **name** (nicer
+ * to read in `.neon`, and still resolvable by every command), falling back to
+ * the id when the branch has no name.
+ */
+const branchPersistValue = (branch) => branch.name ?? branch.id;
+/**
+ * Verify the project (and the org, when supplied) and resolve the org id to
+ * persist.
+ *
+ * The project is always fetched, which both validates it and yields its
+ * `org_id`. When `--org-id` is passed too: if the project reports an org it must
+ * match (else a clear mismatch error); if it reports none, the supplied org is
+ * verified on its own. Without `--org-id` the project's own org is used, falling
+ * back to the org already recorded for the *same* project in `.neon`. Projects
+ * on a personal account have no org, so `undefined` is a valid result — the
+ * field is simply omitted.
+ */
+const resolveOrgForProject = async (props, inputs, existing, projectId) => {
+    const project = await fetchProjectOrThrow(props, projectId);
+    const projectOrg = project.org_id ?? undefined;
+    if (inputs.orgId) {
+        if (projectOrg && projectOrg !== inputs.orgId) {
+            throw new LinkInputError(`Project '${projectId}' belongs to organization '${projectOrg}', not '${inputs.orgId}'. Omit --org-id to use the project's own org, or pass the matching ID.`, 'ORG_MISMATCH');
+        }
+        if (!projectOrg) {
+            await verifyOrgAccess(props, inputs.orgId);
+        }
+        return inputs.orgId;
+    }
+    if (projectOrg) {
+        return projectOrg;
+    }
+    if (projectId === existing.projectId && existing.orgId) {
+        return existing.orgId;
+    }
+    return undefined;
+};
+/**
+ * Resolve the branch to persist alongside a project in non-interactive mode.
+ *
+ * `link` never guesses the project's default branch — that's `checkout`'s job —
+ * so the only sources are an explicit `--branch` (name or id, verified and
+ * normalized to its name) or a branch already pinned for the *same* project (so
+ * re-linking it doesn't drop your checked-out branch). Reading the existing
+ * branch via {@link contextBranch} also recovers a legacy `branchId` field.
+ */
+const resolvePinnedBranch = async (props, inputs, existing, projectId) => {
+    if (inputs.branch) {
+        const branch = await resolveBranchRef(props, projectId, inputs.branch);
+        return branchPersistValue(branch);
+    }
+    if (projectId === existing.projectId) {
+        return contextBranch(existing);
+    }
+    return undefined;
+};
+// ----------------------------------------------------------------------------
 // Non-interactive flag-driven mode
 // ----------------------------------------------------------------------------
-const runNonInteractive = async (props, inputs) => {
-    const orgId = mustString(inputs.orgId, 'orgId');
+const runNonInteractive = async (props, inputs, existing) => {
+    // Create a new project and link it.
+    if (inputs.projectName) {
+        const orgId = mustString(inputs.orgId, 'orgId');
+        await verifyOrgAccess(props, orgId);
+        const created = await createProject(props, {
+            orgId,
+            name: inputs.projectName,
+            regionId: mustString(inputs.regionId, 'regionId'),
+        });
+        applyContext(props.contextFile, {
+            orgId,
+            projectId: created.project.id,
+            branch: created.branchName,
+        });
+        await finalizeLink(props, {
+            contextFile: props.contextFile,
+            orgId,
+            projectId: created.project.id,
+            branch: created.branchName,
+            created: true,
+            projectName: created.project.name,
+            regionId: created.project.region_id,
+        });
+        return;
+    }
+    // Link an explicitly named existing project.
     if (inputs.projectId) {
-        const branchId = await resolveDefaultBranchId(props, inputs.projectId);
+        const orgId = await resolveOrgForProject(props, inputs, existing, inputs.projectId);
+        const branch = await resolvePinnedBranch(props, inputs, existing, inputs.projectId);
         applyContext(props.contextFile, {
             orgId,
             projectId: inputs.projectId,
-            branchId,
+            branch,
         });
-        await finalizeHumanLink(props, {
+        await finalizeLink(props, {
             contextFile: props.contextFile,
             orgId,
             projectId: inputs.projectId,
-            branchId,
+            branch,
             created: false,
         });
         return;
     }
-    const created = await createProject(props, {
-        orgId,
-        name: mustString(inputs.projectName, 'projectName'),
-        regionId: mustString(inputs.regionId, 'regionId'),
-    });
-    applyContext(props.contextFile, {
-        orgId,
-        projectId: created.project.id,
-        branchId: created.branchId,
-    });
-    await finalizeHumanLink(props, {
-        contextFile: props.contextFile,
-        orgId,
-        projectId: created.project.id,
-        branchId: created.branchId,
-        created: true,
-        projectName: created.project.name,
-        regionId: created.project.region_id,
-    });
+    // Pin a branch in the already-linked project.
+    if (inputs.branch && existing.projectId) {
+        const projectId = existing.projectId;
+        const orgId = await resolveOrgForProject(props, inputs, existing, projectId);
+        const branch = await resolvePinnedBranch(props, inputs, existing, projectId);
+        applyContext(props.contextFile, {
+            orgId,
+            projectId,
+            branch,
+        });
+        await finalizeLink(props, {
+            contextFile: props.contextFile,
+            orgId,
+            projectId,
+            branch,
+            created: false,
+        });
+        return;
+    }
+    // Record the default org, preserving any existing project/branch.
+    if (inputs.orgId) {
+        const orgId = inputs.orgId;
+        await verifyOrgAccess(props, orgId);
+        const projectId = existing.projectId;
+        const branch = projectId ? contextBranch(existing) : undefined;
+        applyContext(props.contextFile, { orgId, projectId, branch });
+        printSummary(props, {
+            contextFile: props.contextFile,
+            orgId,
+            projectId,
+            branch,
+            created: false,
+            orgOnly: true,
+        });
+        return;
+    }
 };
 // ----------------------------------------------------------------------------
 // Interactive mode (TTY)
@@ -195,22 +500,6 @@ const runInteractive = async (props, inputs) => {
     else {
         orgId = await promptOrgFromList(orgResolution.orgs);
     }
-    if (inputs.projectId) {
-        const branchId = await resolveInteractiveBranchId(props, inputs.projectId);
-        applyContext(props.contextFile, {
-            orgId,
-            projectId: inputs.projectId,
-            branchId,
-        });
-        await finalizeHumanLink(props, {
-            contextFile: props.contextFile,
-            orgId,
-            projectId: inputs.projectId,
-            branchId,
-            created: false,
-        });
-        return;
-    }
     if (inputs.projectName && inputs.regionId) {
         const created = await createProject(props, {
             orgId,
@@ -220,13 +509,13 @@ const runInteractive = async (props, inputs) => {
         applyContext(props.contextFile, {
             orgId,
             projectId: created.project.id,
-            branchId: created.branchId,
+            branch: created.branchName,
         });
-        await finalizeHumanLink(props, {
+        await finalizeLink(props, {
             contextFile: props.contextFile,
             orgId,
             projectId: created.project.id,
-            branchId: created.branchId,
+            branch: created.branchName,
             created: true,
             projectName: created.project.name,
             regionId: created.project.region_id,
@@ -237,17 +526,17 @@ const runInteractive = async (props, inputs) => {
     const projects = await listAllProjects(props, orgId);
     const action = await promptProjectChoice(projects, inputs.projectName);
     if (action.type === 'existing') {
-        const branchId = await resolveInteractiveBranchId(props, action.projectId);
+        const branch = await resolveInteractiveBranch(props, action.projectId);
         applyContext(props.contextFile, {
             orgId,
             projectId: action.projectId,
-            branchId,
+            branch,
         });
-        await finalizeHumanLink(props, {
+        await finalizeLink(props, {
             contextFile: props.contextFile,
             orgId,
             projectId: action.projectId,
-            branchId,
+            branch,
             created: false,
             projectName: action.name,
             regionId: action.regionId,
@@ -264,13 +553,13 @@ const runInteractive = async (props, inputs) => {
     applyContext(props.contextFile, {
         orgId,
         projectId: created.project.id,
-        branchId: created.branchId,
+        branch: created.branchName,
     });
-    await finalizeHumanLink(props, {
+    await finalizeLink(props, {
         contextFile: props.contextFile,
         orgId,
         projectId: created.project.id,
-        branchId: created.branchId,
+        branch: created.branchName,
         created: true,
         projectName: created.project.name,
         regionId: created.project.region_id,
@@ -297,6 +586,13 @@ const promptOrgFromList = async (orgs) => {
     if (!orgs.length) {
         throw new Error(`You don't belong to any organizations. Create one in the Neon Console first: https://console.neon.tech/`);
     }
+    // A single organization leaves nothing to choose, so skip the prompt and link
+    // it directly — go straight on to the project step.
+    if (orgs.length === 1) {
+        const [only] = orgs;
+        log.info(`Linking organization ${only.name} (${only.id}).`);
+        return only.id;
+    }
     const { orgId } = await prompts({
         onState: onPromptState,
         type: 'select',
@@ -381,31 +677,50 @@ const runAgentSafely = async (props) => {
     }
 };
 const runAgent = async (props, inputs) => {
-    const { projectId, projectName, regionId } = inputs;
-    const orgResolution = await resolveOrg(props, inputs.orgId);
-    if (orgResolution.kind === 'needs_selection') {
-        emitAgent(buildNeedsOrgResponse(orgResolution));
-        return;
-    }
-    const orgId = orgResolution.orgId;
+    const { projectId, projectName, regionId, branch } = inputs;
+    const existing = readContextFile(props.contextFile);
+    // Existing project: infer the org and link it. The branch is left to an
+    // explicit `checkout` unless one was passed or is already pinned.
     if (projectId) {
-        const branchId = await resolveDefaultBranchId(props, projectId);
-        applyContext(props.contextFile, { orgId, projectId, branchId });
-        const pullNote = renderAgentPullNote(await autoPullEnvAfterPin({
-            ...props,
+        const orgId = await resolveOrgForProject(props, inputs, existing, projectId);
+        const pinnedBranch = await resolvePinnedBranch(props, inputs, existing, projectId);
+        applyContext(props.contextFile, {
+            orgId,
             projectId,
-            branch: branchId,
-            envPull: props.envPull,
-        }));
+            branch: pinnedBranch,
+        });
+        const orgSuffix = orgId ? ` (org ${orgId})` : '';
+        if (pinnedBranch) {
+            const pullNote = renderAgentPullNote(await autoPullEnvAfterPin({
+                ...props,
+                projectId,
+                branch: pinnedBranch,
+                envPull: props.envPull,
+            }));
+            emitAgent({
+                status: 'linked',
+                context_file: props.contextFile,
+                context: { orgId, projectId, branch: pinnedBranch },
+                project: { id: projectId },
+                message: `Linked ${props.contextFile} to project ${projectId}${orgSuffix} on branch ${pinnedBranch}.${pullNote}`,
+            });
+            return;
+        }
         emitAgent({
             status: 'linked',
             context_file: props.contextFile,
-            context: { orgId, projectId, branchId },
+            context: { orgId, projectId },
             project: { id: projectId },
-            message: `Linked ${props.contextFile} to project ${projectId} (org ${orgId}) on branch ${branchId}.${pullNote}`,
+            message: `Linked ${props.contextFile} to project ${projectId}${orgSuffix}. No branch pinned — run \`neonctl checkout <branch>\` (omit the branch to list options) to pin one and pull its env vars.`,
         });
         return;
     }
+    const orgResolution = await resolveOrg(props, inputs.orgId);
+    if (orgResolution.kind === 'needs_selection') {
+        emitAgent(buildNeedsOrgResponse(orgResolution));
+        return;
+    }
+    const orgId = orgResolution.orgId;
     if (projectName && !regionId) {
         const regions = await fetchRegions(props);
         emitAgent({
@@ -421,6 +736,7 @@ const runAgent = async (props, inputs) => {
         return;
     }
     if (projectName && regionId) {
+        await verifyOrgAccess(props, orgId);
         const created = await createProject(props, {
             orgId,
             name: projectName,
@@ -429,12 +745,12 @@ const runAgent = async (props, inputs) => {
         applyContext(props.contextFile, {
             orgId,
             projectId: created.project.id,
-            branchId: created.branchId,
+            branch: created.branchName,
         });
         const pullNote = renderAgentPullNote(await autoPullEnvAfterPin({
             ...props,
             projectId: created.project.id,
-            branch: created.branchId,
+            branch: created.branchName,
             envPull: props.envPull,
         }));
         emitAgent({
@@ -443,24 +759,30 @@ const runAgent = async (props, inputs) => {
             context: {
                 orgId,
                 projectId: created.project.id,
-                branchId: created.branchId,
+                branch: created.branchName,
             },
             project: {
                 id: created.project.id,
                 name: created.project.name,
                 region_id: created.project.region_id,
             },
-            message: `Created project ${created.project.id} ("${created.project.name ?? projectName}") in ${created.project.region_id ?? regionId} and linked ${props.contextFile}.${pullNote}`,
+            message: `Created project ${created.project.id} ("${created.project.name ?? projectName}") in ${created.project.region_id ?? regionId} and linked ${props.contextFile} on branch ${created.branchName}.${pullNote}`,
         });
         return;
     }
-    // orgId is set but no project info — list projects to choose from.
+    // orgId is set but no project info — list projects to choose from. A pending
+    // --branch can't be applied until a project is chosen, so it's surfaced in
+    // the instruction rather than silently dropped.
     const projects = await listAllProjects(props, orgId);
+    const branchNote = branch
+        ? ` A branch was requested (--branch ${branch}) but a branch can only be pinned once a project is chosen — re-run with --project-id first, then \`neonctl checkout ${branch}\`.`
+        : '';
     emitAgent({
         status: 'needs_project',
-        instruction: projects.length === 0
+        instruction: (projects.length === 0
             ? `Organization ${orgId} has no projects yet. Ask the user for a name for the new project, then re-run the create_option.next_command_template.`
-            : `Ask the user whether to link to one of these ${projects.length} existing projects (use next_command_template with --project-id) or create a new project (use create_option.next_command_template).`,
+            : `Ask the user whether to link to one of these ${projects.length} existing projects (use next_command_template with --project-id) or create a new project (use create_option.next_command_template).`) +
+            branchNote,
         options: projects.map((project) => ({
             id: project.id,
             name: project.name,
@@ -554,6 +876,9 @@ const buildNeedsOrgResponse = (resolution) => {
     };
 };
 const toAgentError = (err) => {
+    if (err instanceof LinkInputError) {
+        return { status: 'error', code: err.agentCode, message: err.message };
+    }
     if (isAxiosError(err)) {
         const status = err.response?.status;
         const data = err.response?.data;
@@ -604,22 +929,15 @@ const listAllProjects = async (props, orgId) => {
     }
     return result;
 };
-const resolveDefaultBranchId = async (props, projectId) => {
-    const { data } = await props.apiClient.listProjectBranches({ projectId });
-    const branch = data.branches.find((b) => b.default);
-    if (!branch) {
-        throw new Error(`Could not find a default branch for project ${projectId}.`);
-    }
-    return branch.id;
-};
 /**
- * Resolve which branch to pin for an interactively-chosen project. When the project has a
+ * Resolve which branch to pin for an interactively-chosen project, returned as the value to
+ * persist (its name when known, see {@link branchPersistValue}). When the project has a
  * single branch there is nothing to choose, so we pin it silently. Otherwise we offer the
  * shared branch picker (the same "＋ Create a new branch…" + list as `neonctl checkout`),
- * creating the branch when the user opts to. This makes `link` a full org → project →
- * branch flow instead of always pinning the default branch.
+ * creating the branch when the user opts to. This makes interactive `link` a full org →
+ * project → branch flow; non-interactive `link` instead defers the branch to `checkout`.
  */
-const resolveInteractiveBranchId = async (props, projectId) => {
+const resolveInteractiveBranch = async (props, projectId) => {
     const { data } = await props.apiClient.listProjectBranches({ projectId });
     const branches = data.branches;
     if (branches.length <= 1) {
@@ -627,7 +945,7 @@ const resolveInteractiveBranchId = async (props, projectId) => {
         if (!only) {
             throw new Error(`Could not find a default branch for project ${projectId}.`);
         }
-        return only.id;
+        return branchPersistValue(only);
     }
     const picked = await pickBranchInteractively(branches, {
         message: 'Which branch would you like to link?',
@@ -635,9 +953,12 @@ const resolveInteractiveBranchId = async (props, projectId) => {
             'Re-run `neonctl link` interactively, or `neonctl checkout <branch>` to pin one.',
     });
     if (picked.kind === 'existing') {
-        return picked.branchId;
+        const existing = branches.find((b) => b.id === picked.branchId);
+        return existing ? branchPersistValue(existing) : picked.branchId;
     }
-    return createBranch(props.apiClient, projectId, picked.name, branches);
+    // A freshly-created branch: we already know the name the user typed.
+    await createBranch(props.apiClient, projectId, picked.name, branches);
+    return picked.name;
 };
 const fetchRegions = async (props) => {
     try {
@@ -682,31 +1003,50 @@ const createProject = async (props, args) => {
             region_id: data.project.region_id,
         },
         branchId: data.branch.id,
+        branchName: data.branch.name ?? data.branch.id,
     };
 };
-const printHumanSummary = (_props, summary) => {
+const printSummary = (_props, summary) => {
     const lines = [];
     if (summary.created) {
         lines.push(`Created project ${summary.projectId}${summary.projectName ? ` ("${summary.projectName}")` : ''}${summary.regionId ? ` in ${summary.regionId}` : ''}.`);
     }
-    lines.push(`Linked ${summary.contextFile}:`);
-    lines.push(`  orgId:    ${summary.orgId}`);
-    lines.push(`  projectId: ${summary.projectId}`);
-    lines.push(`  branchId:  ${summary.branchId}`);
+    lines.push(`${summary.orgOnly ? 'Updated' : 'Linked'} ${summary.contextFile}:`);
+    if (summary.orgId) {
+        lines.push(`  orgId:     ${summary.orgId}`);
+    }
+    if (summary.projectId) {
+        lines.push(`  projectId: ${summary.projectId}`);
+    }
+    if (summary.branch) {
+        lines.push(`  branch:    ${summary.branch}`);
+    }
+    if (summary.noChecks) {
+        lines.push('');
+        lines.push('Written offline (--no-checks): nothing was verified.');
+    }
+    else if (summary.projectId && !summary.branch && !summary.orgOnly) {
+        lines.push('');
+        lines.push('No branch pinned. Run `neonctl checkout <branch>` to pin a branch and pull its env vars.');
+    }
     lines.push('');
     process.stdout.write(`${lines.join('\n')}\n`);
 };
 /**
- * Print the link summary, then run the bundled `env pull` so a human `link` ends with the
- * branch's connection string already on disk — the branch-first loop is just link + checkout.
+ * Print the link summary, then run the bundled `env pull` so a human `link` that pinned a
+ * branch ends with the branch's connection string already on disk. When no branch was pinned
+ * there is nothing to pull, so env pull is skipped and the summary nudges `checkout` instead.
  * `--no-env-pull` opts out (env pull's own status / skip hint is logged to stderr).
  */
-const finalizeHumanLink = async (props, summary) => {
-    printHumanSummary(props, summary);
+const finalizeLink = async (props, summary) => {
+    printSummary(props, summary);
+    if (!summary.branch || !summary.projectId) {
+        return;
+    }
     await autoPullEnvAfterPin({
         ...props,
         projectId: summary.projectId,
-        branch: summary.branchId,
+        branch: summary.branch,
         envPull: props.envPull,
     });
 };