neonctl 2.28.0 → 2.29.0

package/dist/commands/link.js

@@ -1,95 +1,99 @@
-import { isNeonApiError, messageFromBody } from '../api.js';
-import prompts from 'prompts';
-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';
-import { autoPullEnvAfterPin, renderAgentPullNote } from './env.js';
-import { REGIONS } from './projects.js';
+import prompts from "prompts";
+import { isNeonApiError, messageFromBody } from "../api.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";
+import { hasNeonConfigFile, initCmd } from "./config.js";
+import { autoPullEnvAfterPin, renderAgentPullNote } from "./env.js";
+import { REGIONS } from "./projects.js";
 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';
+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]')
+    .usage("$0 link [options]")
     .options({
-    'org-id': {
-        describe: 'Organization ID to link to',
-        type: 'string',
+    "org-id": {
+        describe: "Organization ID to link to",
+        type: "string",
     },
-    'project-id': {
-        describe: 'Existing project ID to link to',
-        type: 'string',
+    "project-id": {
+        describe: "Existing project ID to link to",
+        type: "string",
     },
-    'project-name': {
-        describe: 'Name for a new project to create and link to',
-        type: 'string',
+    "project-name": {
+        describe: "Name for a new project to create and link to",
+        type: "string",
     },
-    'region-id': {
-        describe: 'Region ID for a new project (e.g. aws-us-east-2). Required with --project-name.',
-        type: 'string',
+    "region-id": {
+        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',
+        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',
+        type: "string",
     },
     agent: {
-        describe: 'Emit a JSON state-machine response designed for AI agents instead of prompting. The output is a single JSON object with a discriminated `status` field describing the next step.',
-        type: 'boolean',
+        describe: "Emit a JSON state-machine response designed for AI agents instead of prompting. The output is a single JSON object with a discriminated `status` field describing the next step.",
+        type: "boolean",
         default: false,
     },
     yes: {
-        alias: 'y',
+        alias: "y",
         describe: 'Skip the "already linked" confirmation in interactive mode and re-link anyway.',
-        type: 'boolean',
+        type: "boolean",
         default: false,
     },
     clear: {
-        describe: 'Remove the org/project/branch context (writes an empty context file) instead of linking.',
-        type: 'boolean',
+        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',
+        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': {
+    "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`). Only runs when a branch is pinned.',
-        type: 'boolean',
+            "linking. On by default; use --no-env-pull to skip (e.g. when injecting env at " +
+            "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',
+        "$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 --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 --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 --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",
     ],
-    ['$0 link --clear', 'Forget the current org/project/branch context'],
 ]);
 export const handler = async (props) => {
     if (props.clear) {
@@ -113,13 +117,13 @@ export const handler = async (props) => {
     }
     if (isCi()) {
         log.error([
-            'Missing inputs and CI environment detected (no TTY for prompts).',
-            '',
-            'Use one of:',
-            '  neonctl link --agent                                                    (JSON state machine for agents)',
-            '  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'));
+            "Missing inputs and CI environment detected (no TTY for prompts).",
+            "",
+            "Use one of:",
+            "  neonctl link --agent                                                    (JSON state machine for agents)",
+            "  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);
         return;
     }
@@ -130,7 +134,7 @@ export const handler = async (props) => {
 // ----------------------------------------------------------------------------
 const parseInputs = (props) => {
     let fromParams = {};
-    if (props.params !== undefined && props.params !== '') {
+    if (props.params !== undefined && props.params !== "") {
         let parsed;
         try {
             parsed = JSON.parse(props.params);
@@ -150,33 +154,33 @@ const parseInputs = (props) => {
     };
 };
 const extractParams = (raw) => {
-    if (raw === null || typeof raw !== 'object') {
-        throw new Error('--params must be a JSON object');
+    if (raw === null || typeof raw !== "object") {
+        throw new Error("--params must be a JSON object");
     }
     const obj = raw;
     const pickString = (key) => {
         const value = obj[key];
         if (value === undefined || value === null)
             return undefined;
-        if (typeof value !== 'string') {
+        if (typeof value !== "string") {
             throw new Error(`--params.${key} must be a string`);
         }
         return value;
     };
     return {
-        orgId: pickString('orgId'),
-        projectId: pickString('projectId'),
-        projectName: pickString('projectName'),
-        regionId: pickString('regionId'),
-        branch: pickString('branch') ?? pickString('branchId'),
+        orgId: pickString("orgId"),
+        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.');
+        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>`.');
+        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>`.");
     }
 };
 /**
@@ -224,7 +228,7 @@ const runWithoutChecks = (props) => {
         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).');
+        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,
@@ -233,7 +237,7 @@ const runWithoutChecks = (props) => {
     });
     if (props.agent) {
         emitAgent({
-            status: 'linked',
+            status: "linked",
             context_file: props.contextFile,
             context: {
                 orgId: inputs.orgId,
@@ -241,7 +245,7 @@ const runWithoutChecks = (props) => {
                 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.`,
+            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;
     }
@@ -263,7 +267,7 @@ const runWithoutChecks = (props) => {
 class LinkInputError extends Error {
     constructor(message, agentCode) {
         super(message);
-        this.name = 'LinkInputError';
+        this.name = "LinkInputError";
         this.agentCode = agentCode;
     }
 }
@@ -284,10 +288,10 @@ const fetchProjectOrThrow = async (props, projectId) => {
             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');
+            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 new LinkInputError(`Project '${projectId}' not found. Double-check the project ID — or that your API key has access to it.`, "NOT_FOUND");
         }
         throw err;
     }
@@ -310,7 +314,7 @@ const verifyOrgAccess = async (props, orgId) => {
             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 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;
     }
@@ -331,10 +335,10 @@ const resolveBranchRef = async (props, projectId, branchRef) => {
     }
     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');
+            .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
@@ -359,7 +363,7 @@ const resolveOrgForProject = async (props, inputs, existing, 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');
+            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);
@@ -399,12 +403,12 @@ const resolvePinnedBranch = async (props, inputs, existing, projectId) => {
 const runNonInteractive = async (props, inputs, existing) => {
     // Create a new project and link it.
     if (inputs.projectName) {
-        const orgId = mustString(inputs.orgId, 'orgId');
+        const orgId = mustString(inputs.orgId, "orgId");
         await verifyOrgAccess(props, orgId);
         const created = await createProject(props, {
             orgId,
             name: inputs.projectName,
-            regionId: mustString(inputs.regionId, 'regionId'),
+            regionId: mustString(inputs.regionId, "regionId"),
         });
         applyContext(props.contextFile, {
             orgId,
@@ -486,16 +490,16 @@ const runInteractive = async (props, inputs) => {
     }
     const orgResolution = await resolveOrg(props, inputs.orgId);
     let orgId;
-    if (orgResolution.kind === 'resolved') {
+    if (orgResolution.kind === "resolved") {
         orgId = orgResolution.orgId;
         if (orgResolution.autoDetected) {
             log.info(`Detected organization ${orgId} from your existing projects (organization-scoped API key).`);
         }
     }
     else if (orgResolution.orgKeyLimited) {
-        throw new Error('This API key is organization-scoped, so the CLI cannot list your organizations, ' +
-            'and no existing project was found in this org to auto-detect the ID. ' +
-            'Re-run with `--org-id <your_org_id>` (find it in the Neon Console under Settings).');
+        throw new Error("This API key is organization-scoped, so the CLI cannot list your organizations, " +
+            "and no existing project was found in this org to auto-detect the ID. " +
+            "Re-run with `--org-id <your_org_id>` (find it in the Neon Console under Settings).");
     }
     else {
         orgId = await promptOrgFromList(orgResolution.orgs);
@@ -511,7 +515,7 @@ const runInteractive = async (props, inputs) => {
             projectId: created.project.id,
             branch: created.branchName,
         });
-        await finalizeLink(props, {
+        await finalizeInteractiveLink(props, {
             contextFile: props.contextFile,
             orgId,
             projectId: created.project.id,
@@ -525,14 +529,14 @@ const runInteractive = async (props, inputs) => {
     // Need to ask: existing project or create a new one?
     const projects = await listAllProjects(props, orgId);
     const action = await promptProjectChoice(projects, inputs.projectName);
-    if (action.type === 'existing') {
+    if (action.type === "existing") {
         const branch = await resolveInteractiveBranch(props, action.projectId);
         applyContext(props.contextFile, {
             orgId,
             projectId: action.projectId,
             branch,
         });
-        await finalizeLink(props, {
+        await finalizeInteractiveLink(props, {
             contextFile: props.contextFile,
             orgId,
             projectId: action.projectId,
@@ -555,7 +559,7 @@ const runInteractive = async (props, inputs) => {
         projectId: created.project.id,
         branch: created.branchName,
     });
-    await finalizeLink(props, {
+    await finalizeInteractiveLink(props, {
         contextFile: props.contextFile,
         orgId,
         projectId: created.project.id,
@@ -572,13 +576,13 @@ const confirmRelinkIfNeeded = async (props) => {
     }
     const { proceed } = await prompts({
         onState: onPromptState,
-        type: 'confirm',
-        name: 'proceed',
+        type: "confirm",
+        name: "proceed",
         message: `${props.contextFile} is already linked to project ${existing.projectId} (org ${existing.orgId}). Re-link?`,
         initial: true,
     });
     if (!proceed) {
-        process.stdout.write('Aborted. Existing link preserved.\n');
+        process.stdout.write("Aborted. Existing link preserved.\n");
         process.exit(0);
     }
 };
@@ -595,9 +599,9 @@ const promptOrgFromList = async (orgs) => {
     }
     const { orgId } = await prompts({
         onState: onPromptState,
-        type: 'select',
-        name: 'orgId',
-        message: 'Which organization would you like to link?',
+        type: "select",
+        name: "orgId",
+        message: "Which organization would you like to link?",
         choices: orgs.map((org) => ({
             title: `${org.name} (${org.id})`,
             value: org.id,
@@ -608,7 +612,7 @@ const promptOrgFromList = async (orgs) => {
 };
 const promptProjectChoice = async (projects, suggestedName) => {
     const choices = [
-        { title: '＋ Create new project…', value: CREATE_NEW_SENTINEL },
+        { title: "＋ Create new project…", value: CREATE_NEW_SENTINEL },
         ...projects.map((project) => ({
             title: `${project.name} (${project.id})`,
             value: project.id,
@@ -618,18 +622,18 @@ const promptProjectChoice = async (projects, suggestedName) => {
     // is one; with no projects to show, the create option (index 0) is the only choice.
     const { selection } = await prompts({
         onState: onPromptState,
-        type: 'select',
-        name: 'selection',
-        message: 'Which project would you like to link?',
+        type: "select",
+        name: "selection",
+        message: "Which project would you like to link?",
         choices,
         initial: projects.length > 0 ? 1 : 0,
     });
     if (selection === CREATE_NEW_SENTINEL) {
-        return { type: 'create', suggestedName };
+        return { type: "create", suggestedName };
     }
     const project = projects.find((p) => p.id === selection);
     return {
-        type: 'existing',
+        type: "existing",
         projectId: selection,
         name: project?.name,
         regionId: project?.region_id,
@@ -638,11 +642,13 @@ const promptProjectChoice = async (projects, suggestedName) => {
 const promptProjectName = async (suggestedName) => {
     const { name } = await prompts({
         onState: onPromptState,
-        type: 'text',
-        name: 'name',
-        message: 'Name for the new project:',
+        type: "text",
+        name: "name",
+        message: "Name for the new project:",
         initial: suggestedName,
-        validate: (value) => value && value.trim().length > 0 ? true : 'Project name is required',
+        validate: (value) => value && value.trim().length > 0
+            ? true
+            : "Project name is required",
     });
     return String(name).trim();
 };
@@ -651,9 +657,9 @@ const promptRegion = async (props) => {
     const defaultIndex = Math.max(0, regions.findIndex((r) => r.default));
     const { regionId } = await prompts({
         onState: onPromptState,
-        type: 'select',
-        name: 'regionId',
-        message: 'Which region should the new project run in?',
+        type: "select",
+        name: "regionId",
+        message: "Which region should the new project run in?",
         choices: regions.map((region) => ({
             title: `${region.name} (${region.region_id})`,
             value: region.region_id,
@@ -689,7 +695,7 @@ const runAgent = async (props, inputs) => {
             projectId,
             branch: pinnedBranch,
         });
-        const orgSuffix = orgId ? ` (org ${orgId})` : '';
+        const orgSuffix = orgId ? ` (org ${orgId})` : "";
         if (pinnedBranch) {
             const pullNote = renderAgentPullNote(await autoPullEnvAfterPin({
                 ...props,
@@ -698,7 +704,7 @@ const runAgent = async (props, inputs) => {
                 envPull: props.envPull,
             }));
             emitAgent({
-                status: 'linked',
+                status: "linked",
                 context_file: props.contextFile,
                 context: { orgId, projectId, branch: pinnedBranch },
                 project: { id: projectId },
@@ -707,7 +713,7 @@ const runAgent = async (props, inputs) => {
             return;
         }
         emitAgent({
-            status: 'linked',
+            status: "linked",
             context_file: props.contextFile,
             context: { orgId, projectId },
             project: { id: projectId },
@@ -716,7 +722,7 @@ const runAgent = async (props, inputs) => {
         return;
     }
     const orgResolution = await resolveOrg(props, inputs.orgId);
-    if (orgResolution.kind === 'needs_selection') {
+    if (orgResolution.kind === "needs_selection") {
         emitAgent(buildNeedsOrgResponse(orgResolution));
         return;
     }
@@ -724,7 +730,7 @@ const runAgent = async (props, inputs) => {
     if (projectName && !regionId) {
         const regions = await fetchRegions(props);
         emitAgent({
-            status: 'needs_project_details',
+            status: "needs_project_details",
             instruction: `Ask the user which region to create project "${projectName}" in. After they pick one, re-run the next_command_template with the chosen --region-id value.`,
             regions: regions.map((region) => ({
                 id: region.region_id,
@@ -754,7 +760,7 @@ const runAgent = async (props, inputs) => {
             envPull: props.envPull,
         }));
         emitAgent({
-            status: 'linked',
+            status: "linked",
             context_file: props.contextFile,
             context: {
                 orgId,
@@ -776,9 +782,9 @@ const runAgent = async (props, inputs) => {
     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',
+        status: "needs_project",
         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).`) +
@@ -789,7 +795,7 @@ const runAgent = async (props, inputs) => {
             region_id: project.region_id,
         })),
         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.',
+            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 ${shellArg(orgId)} --project-name <name> --region-id <region_id>`,
         },
         next_command_template: `neonctl link --agent --org-id ${shellArg(orgId)} --project-id <project_id>`,
@@ -801,12 +807,13 @@ const emitAgent = (response) => {
 // ----------------------------------------------------------------------------
 // API helpers
 // ----------------------------------------------------------------------------
-const ORG_KEY_LIMITED_FRAGMENT = 'not allowed for organization API keys';
+const ORG_KEY_LIMITED_FRAGMENT = "not allowed for organization API keys";
 const isOrgKeyLimitedError = (err) => {
     if (!isNeonApiError(err))
         return false;
     const message = messageFromBody(err.data);
-    return (typeof message === 'string' && message.includes(ORG_KEY_LIMITED_FRAGMENT));
+    return (typeof message === "string" &&
+        message.includes(ORG_KEY_LIMITED_FRAGMENT));
 };
 const fetchOrganizations = async (props) => {
     const { data } = await props.apiClient.getCurrentUserOrganizations();
@@ -823,23 +830,23 @@ const fetchOrganizations = async (props) => {
  */
 const resolveOrg = async (props, given) => {
     if (given) {
-        return { kind: 'resolved', orgId: given, autoDetected: false };
+        return { kind: "resolved", orgId: given, autoDetected: false };
     }
     try {
         const orgs = await fetchOrganizations(props);
-        return { kind: 'needs_selection', orgs, orgKeyLimited: false };
+        return { kind: "needs_selection", orgs, orgKeyLimited: false };
     }
     catch (err) {
         if (!isOrgKeyLimitedError(err)) {
             throw err;
         }
-        log.debug('getCurrentUserOrganizations not allowed (org-scoped API key); attempting to derive org from existing projects.');
+        log.debug("getCurrentUserOrganizations not allowed (org-scoped API key); attempting to derive org from existing projects.");
     }
     const detected = await detectOrgIdFromProjects(props);
     if (detected) {
-        return { kind: 'resolved', orgId: detected, autoDetected: true };
+        return { kind: "resolved", orgId: detected, autoDetected: true };
     }
-    return { kind: 'needs_selection', orgs: [], orgKeyLimited: true };
+    return { kind: "needs_selection", orgs: [], orgKeyLimited: true };
 };
 const detectOrgIdFromProjects = async (props) => {
     try {
@@ -848,32 +855,32 @@ const detectOrgIdFromProjects = async (props) => {
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        log.debug('detectOrgIdFromProjects failed: %s', message);
+        log.debug("detectOrgIdFromProjects failed: %s", message);
         return undefined;
     }
 };
 const buildNeedsOrgResponse = (resolution) => {
     if (resolution.orgKeyLimited) {
         return {
-            status: 'needs_org',
+            status: "needs_org",
             instruction: "This Neon API key is organization-scoped, so the CLI cannot list the user's organizations and no existing project was found to auto-detect the org ID. Ask the user for their Neon organization ID (visible in the Neon Console under the org's Settings page, formatted like `org-bitter-breeze-12345678`) and re-run the next_command_template with that --org-id.",
             options: [],
-            next_command_template: 'neonctl link --agent --org-id <org_id>',
+            next_command_template: "neonctl link --agent --org-id <org_id>",
         };
     }
     const orgs = resolution.orgs;
     return {
-        status: 'needs_org',
+        status: "needs_org",
         instruction: orgs.length === 0
-            ? 'The user does not belong to any organizations. Ask them to create one in the Neon Console (https://console.neon.tech/) before linking.'
-            : `Ask the user which of these ${orgs.length} organization${orgs.length === 1 ? '' : 's'} they want to link the current directory to. After they pick one, re-run the next_command_template with the chosen --org-id value.`,
+            ? "The user does not belong to any organizations. Ask them to create one in the Neon Console (https://console.neon.tech/) before linking."
+            : `Ask the user which of these ${orgs.length} organization${orgs.length === 1 ? "" : "s"} 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: orgs.map((org) => ({ id: org.id, name: org.name })),
-        next_command_template: 'neonctl link --agent --org-id <org_id>',
+        next_command_template: "neonctl link --agent --org-id <org_id>",
     };
 };
 const toAgentError = (err) => {
     if (err instanceof LinkInputError) {
-        return { status: 'error', code: err.agentCode, message: err.message };
+        return { status: "error", code: err.agentCode, message: err.message };
     }
     if (isNeonApiError(err)) {
         const status = err.status;
@@ -881,27 +888,31 @@ const toAgentError = (err) => {
         const message = apiMessage !== undefined && apiMessage.length > 0
             ? apiMessage
             : err.message;
-        let code = 'API_ERROR';
+        let code = "API_ERROR";
         if (status === 401 || status === 403) {
-            code = 'AUTH_ERROR';
+            code = "AUTH_ERROR";
         }
         else if (status !== undefined && status >= 400 && status < 500) {
-            code = 'CLIENT_ERROR';
+            code = "CLIENT_ERROR";
         }
         else if (status !== undefined && status >= 500) {
-            code = 'SERVER_ERROR';
+            code = "SERVER_ERROR";
         }
-        else if (err.code === 'ECONNABORTED') {
-            code = 'TIMEOUT';
+        else if (err.code === "ECONNABORTED") {
+            code = "TIMEOUT";
         }
-        return { status: 'error', code, message };
+        return { status: "error", code, message };
     }
     if (err instanceof Error) {
-        return { status: 'error', code: 'INTERNAL_ERROR', message: err.message };
+        return {
+            status: "error",
+            code: "INTERNAL_ERROR",
+            message: err.message,
+        };
     }
     return {
-        status: 'error',
-        code: 'INTERNAL_ERROR',
+        status: "error",
+        code: "INTERNAL_ERROR",
         message: String(err),
     };
 };
@@ -941,11 +952,11 @@ const resolveInteractiveBranch = async (props, projectId) => {
         return branchPersistValue(only);
     }
     const picked = await pickBranchInteractively(branches, {
-        message: 'Which branch would you like to link?',
-        nonInteractiveMessage: 'No branch could be selected without an interactive terminal. ' +
-            'Re-run `neonctl link` interactively, or `neonctl checkout <branch>` to pin one.',
+        message: "Which branch would you like to link?",
+        nonInteractiveMessage: "No branch could be selected without an interactive terminal. " +
+            "Re-run `neonctl link` interactively, or `neonctl checkout <branch>` to pin one.",
     });
-    if (picked.kind === 'existing') {
+    if (picked.kind === "existing") {
         const existing = branches.find((b) => b.id === picked.branchId);
         return existing ? branchPersistValue(existing) : picked.branchId;
     }
@@ -962,11 +973,11 @@ const fetchRegions = async (props) => {
     }
     catch (err) {
         if (isNeonApiError(err)) {
-            log.debug('getActiveRegions failed (%s), falling back to the static region list.', err.status ?? err.code ?? err.message);
+            log.debug("getActiveRegions failed (%s), falling back to the static region list.", err.status ?? err.code ?? err.message);
         }
         else {
             const message = err instanceof Error ? err.message : String(err);
-            log.debug('getActiveRegions failed (%s), falling back to the static region list.', message);
+            log.debug("getActiveRegions failed (%s), falling back to the static region list.", message);
         }
     }
     return staticRegionsFallback();
@@ -974,9 +985,9 @@ const fetchRegions = async (props) => {
 const staticRegionsFallback = () => REGIONS.map((id) => ({
     region_id: id,
     name: id,
-    default: id === 'aws-us-east-2',
-    geo_lat: '',
-    geo_long: '',
+    default: id === "aws-us-east-2",
+    geo_lat: "",
+    geo_long: "",
 }));
 const createProject = async (props, args) => {
     const project = {
@@ -987,7 +998,7 @@ const createProject = async (props, args) => {
     };
     const { data } = await props.apiClient.createProject({ project });
     if (!data.branch?.id) {
-        throw new Error('Project was created but the API response did not include a default branch id.');
+        throw new Error("Project was created but the API response did not include a default branch id.");
     }
     return {
         project: {
@@ -1002,9 +1013,9 @@ const createProject = async (props, args) => {
 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(`Created project ${summary.projectId}${summary.projectName ? ` ("${summary.projectName}")` : ""}${summary.regionId ? ` in ${summary.regionId}` : ""}.`);
     }
-    lines.push(`${summary.orgOnly ? 'Updated' : 'Linked'} ${summary.contextFile}:`);
+    lines.push(`${summary.orgOnly ? "Updated" : "Linked"} ${summary.contextFile}:`);
     if (summary.orgId) {
         lines.push(`  orgId:     ${summary.orgId}`);
     }
@@ -1015,15 +1026,15 @@ const printSummary = (_props, summary) => {
         lines.push(`  branch:    ${summary.branch}`);
     }
     if (summary.noChecks) {
-        lines.push('');
-        lines.push('Written offline (--no-checks): nothing was verified.');
+        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("");
+        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`);
+    lines.push("");
+    process.stdout.write(`${lines.join("\n")}\n`);
 };
 /**
  * Print the link summary, then run the bundled `env pull` so a human `link` that pinned a
@@ -1043,10 +1054,56 @@ const finalizeLink = async (props, summary) => {
         envPull: props.envPull,
     });
 };
+/**
+ * Interactive `link` finalize: the shared {@link finalizeLink} (summary + env
+ * pull), then — as the last step — offer to manage the project's Neon setup as
+ * code with a `neon.ts`. Kept out of {@link finalizeLink} so the non-interactive
+ * paths never prompt.
+ */
+const finalizeInteractiveLink = async (props, summary) => {
+    await finalizeLink(props, summary);
+    await maybeOfferConfigInit(props, summary);
+};
+/**
+ * Offer to set up infrastructure-as-code at the end of an interactive `link` —
+ * the natural moment, since the project is now linked. Skipped when the project
+ * already has a `neon.ts` (nothing to scaffold). On yes, `config init` writes the
+ * starter `neon.ts` and installs the config packages, then env is pulled again so
+ * the local `.env` reflects the policy — the same pull `link` runs when a project
+ * already ships a `neon.ts`.
+ */
+const maybeOfferConfigInit = async (props, summary) => {
+    const cwd = process.cwd();
+    if (hasNeonConfigFile(cwd)) {
+        return;
+    }
+    const { value } = await prompts({
+        onState: onPromptState,
+        type: "confirm",
+        name: "value",
+        message: "Manage this project's Neon setup as code? Adds a neon.ts you can edit and apply with `neon config apply`.",
+        initial: true,
+    });
+    if (value !== true) {
+        return;
+    }
+    await initCmd({ cwd, install: true });
+    // The neon.ts (and its deps) now exist — pull env again so the local .env
+    // reflects the policy, matching how `link` pulls when a project already ships
+    // a neon.ts. Only meaningful when a branch was pinned (same guard as finalize).
+    if (summary.branch && summary.projectId) {
+        await autoPullEnvAfterPin({
+            ...props,
+            projectId: summary.projectId,
+            branch: summary.branch,
+            envPull: props.envPull,
+        });
+    }
+};
 const onPromptState = (state) => {
     if (state.aborted) {
-        process.stdout.write('\x1B[?25h');
-        process.stdout.write('\n');
+        process.stdout.write("\x1B[?25h");
+        process.stdout.write("\n");
         process.exit(1);
     }
 };