neonctl 2.37.0 → 2.38.0

package/dist/commands/checkout.js

@@ -1,321 +0,0 @@
-import chalk from "chalk";
-import prompts from "prompts";
-import { isNeonApiError } from "../api.js";
-import { applyContext, contextBranch, readContextFile } from "../context.js";
-import { isCi } from "../env.js";
-import { log } from "../log.js";
-import { createBranch, pickBranchInteractively, } from "../utils/branch_picker.js";
-import { fillSingleProject } from "../utils/enrichers.js";
-import { looksLikeBranchId } from "../utils/formats.js";
-import { applyPolicyOnCreate, createBranchFromPolicyOnCheckout, } from "./config.js";
-import { autoPullEnvAfterPin } from "./env.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",
-    },
-    "env-pull": {
-        describe: "Pull the branch's Neon env vars (DATABASE_URL, …) into a local .env after " +
-            "checkout. On by default; use --no-env-pull to skip (e.g. when injecting env at " +
-            "runtime with `neon-env run` / `neon dev`).",
-        type: "boolean",
-        default: true,
-    },
-})
-    .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) => {
-    // Show where the context is pinned *before* we switch it, so the user sees the move
-    // ("currently on X" → "checked out Y") and can catch a checkout they didn't mean to make.
-    // Read straight from `.neon` (a name, no API call); silent when nothing is pinned yet.
-    const previousBranch = contextBranch(readContextFile(props.contextFile));
-    if (previousBranch) {
-        log.info("%s Currently on branch %s", chalk.dim("→"), chalk.cyan.bold(previousBranch));
-    }
-    // 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, branchName, created, policyApplied, policyFailure } = await resolveBranchId(props, projectId);
-    const orgId = await resolveOrgId(props, projectId);
-    // `checkout` is a thin helper over `link`. It fully "heals" the context file:
-    // it always (re)writes `projectId`, `branch`, and `orgId` (when the project
-    // has one) so a `.neon` that drifted or was missing fields ends up complete
-    // and consistent after checkout. The branch is stored as its name when known
-    // (see `link`'s `branch` field), matching what `link` writes.
-    applyContext(props.contextFile, {
-        projectId,
-        ...(orgId ? { orgId } : {}),
-        branch: branchName,
-    });
-    log.info("Checked out branch %s on project %s%s. Updated %s.", branchId, projectId, orgId ? ` (org ${orgId})` : "", props.contextFile);
-    // When checkout *created* the branch and a neon.ts exists, the branch was created straight
-    // from the policy (evaluated as a new branch) so its settings/infra are already applied —
-    // see `policyApplied`. The fallback below covers the case where the branch was created bare
-    // (e.g. a policy-driven create wasn't possible); `applyPolicyOnCreate` is a no-op when there
-    // is no neon.ts on disk. Checking out an existing branch never reconciles it.
-    const failure = created && !policyApplied
-        ? await applyPolicyOrDescribeFailure({
-            projectId,
-            branchId,
-            ...(props.apiKey ? { apiKey: props.apiKey } : {}),
-            ...(props.apiHost ? { apiHost: props.apiHost } : {}),
-            ...(props.color !== undefined
-                ? { color: props.color }
-                : {}),
-        })
-        : policyFailure;
-    // Bundle `env pull` so the branch-first loop is just link + checkout: the branch you
-    // checked out is immediately usable for local dev. `--no-env-pull` opts out.
-    await autoPullEnvAfterPin({
-        ...props,
-        projectId,
-        branch: branchId,
-        envPull: props.envPull,
-    });
-    // A policy that didn't fully apply is reported last, after the pin and the env pull, so the
-    // created branch is left in a consistent, usable, re-runnable state: the failure is what
-    // needs fixing, not the checkout. Still a non-zero exit — the branch does not match the
-    // policy, and `checkout` will not reconcile it on a second run.
-    if (failure) {
-        throw new Error([
-            `Branch ${branchName} (${branchId}) was created and checked out, but applying neon.ts to it failed: ${failure}`,
-            "The branch is usable but does not match the policy, and `neonctl checkout` never reconciles a branch that already exists.",
-            `Fix the cause above, then run \`neonctl deploy --update-existing\` to apply the policy to it — or, if your policy only configures new branches (keyed on \`!branch.exists\`), delete the branch and check it out again: \`neonctl branches delete ${branchName}\` then \`neonctl checkout ${branchName}\`.`,
-        ].join("\n"));
-    }
-};
-/**
- * Apply the policy to a branch `checkout` just created bare, returning the failure message
- * instead of throwing it. The branch and the context pin already stand at this point, so a
- * failed apply must not abort the rest of the checkout — the handler reports it at the end.
- */
-const applyPolicyOrDescribeFailure = async (props) => {
-    try {
-        await applyPolicyOnCreate(props);
-        return undefined;
-    }
-    catch (err) {
-        return err instanceof Error ? err.message : String(err);
-    }
-};
-const resolveBranchId = async (props, projectId) => {
-    const branches = (await props.apiClient.listProjectBranches({ projectId }))
-        .data.branches;
-    if (!props.id) {
-        const picked = await pickBranchInteractively(branches, {
-            message: "Which branch would you like to check out?",
-            nonInteractiveMessage: "No branch specified. Pass a branch name or id (e.g. `neonctl checkout main`), " +
-                "or run interactively to pick one from a list.",
-        });
-        if (picked.kind === "existing") {
-            const existing = branches.find((b) => b.id === picked.branchId);
-            return {
-                branchId: picked.branchId,
-                branchName: existing?.name ?? picked.branchId,
-                created: false,
-                policyApplied: false,
-            };
-        }
-        // The user chose "create a new branch" from the picker.
-        return createCheckoutBranch(props, projectId, picked.name, branches);
-    }
-    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 {
-                branchId: byId.id,
-                branchName: byId.name ?? byId.id,
-                created: false,
-                policyApplied: false,
-            };
-        }
-        throw new Error(notFoundMessage(ref, branches));
-    }
-    const byName = branches.find((b) => b.name === ref);
-    if (byName) {
-        return {
-            branchId: byName.id,
-            branchName: byName.name ?? byName.id,
-            created: false,
-            policyApplied: false,
-        };
-    }
-    // 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 createCheckoutBranch(props, projectId, ref, branches);
-};
-/**
- * Create the branch to check out. When a `neon.ts` exists, route through the policy-driven
- * create so the new branch comes up branched from the policy's `parent` and configured with
- * its declared TTL / compute / services (evaluated as a *new* branch). Otherwise fall back to
- * a bare branch off the default — the handler then applies the policy (a no-op with no
- * `neon.ts`).
- */
-const createCheckoutBranch = async (props, projectId, name, branches) => {
-    const fromPolicy = await createBranchFromPolicyOnCheckout({
-        projectId,
-        branchName: name,
-        ...(props.apiKey ? { apiKey: props.apiKey } : {}),
-        ...(props.apiHost ? { apiHost: props.apiHost } : {}),
-        ...(props.color !== undefined ? { color: props.color } : {}),
-    });
-    if (fromPolicy) {
-        return {
-            branchId: fromPolicy.branchId,
-            branchName: name,
-            created: true,
-            policyApplied: true,
-            ...(fromPolicy.policyFailure
-                ? { policyFailure: fromPolicy.policyFailure }
-                : {}),
-        };
-    }
-    return {
-        branchId: await createBranch(props.apiClient, projectId, name, branches),
-        branchName: name,
-        created: true,
-        policyApplied: false,
-    };
-};
-const notFoundMessage = (ref, branches) => `Branch ${ref} not found.\nAvailable branches: ${branches
-    .map((b) => b.name)
-    .join(", ")}`;
-/**
- * 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 (isNeonApiError(err) && err.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,
-        clear: false,
-        checks: true,
-    });
-    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 (isNeonApiError(err)) {
-            throw err;
-        }
-        log.debug("checkout: could not auto-detect a single project: %s", err instanceof Error ? err.message : String(err));
-        return undefined;
-    }
-};