neon 3.0.0 → 3.1.0

package/dist/commands/checkout.js

@@ -1,322 +1,237 @@
-import chalk from "chalk";
-import prompts from "prompts";
-import { isNeonApiError } from "../api.js";
-import { applyContext, contextBranch, readContextFile } from "../context.js";
+import { __exportAll } from "../_virtual/_rolldown/runtime.js";
 import { isCi } from "../env.js";
 import { log } from "../log.js";
-import { createBranch, pickBranchInteractively, } from "../utils/branch_picker.js";
+import { isNeonApiError } from "../api.js";
+import { applyContext, contextBranch, readContextFile } from "../context.js";
 import { getCliName } from "../utils/cli_name.js";
-import { fillSingleProject } from "../utils/enrichers.js";
 import { looksLikeBranchId } from "../utils/formats.js";
-import { applyPolicyOnCreate, createBranchFromPolicyOnCheckout, } from "./config.js";
+import { fillSingleProject } from "../utils/enrichers.js";
+import { createBranch, pickBranchInteractively } from "../utils/branch_picker.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",
-    ],
+import { applyPolicyOnCreate, createBranchFromPolicyOnCheckout } from "./config.js";
+import { handler as handler$1 } from "./link.js";
+import chalk from "chalk";
+import prompts from "prompts";
+//#region src/commands/checkout.ts
+var checkout_exports = /* @__PURE__ */ __exportAll({
+	builder: () => builder,
+	command: () => command,
+	describe: () => describe,
+	handler: () => handler
+});
+const command = "checkout [id|name]";
+const describe = "Pin a branch in the local context (.neon) so subsequent commands target it";
+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 \`${getCliName()} checkout\` never reconciles a branch that already exists.`,
-            `Fix the cause above, then run \`${getCliName()} 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: \`${getCliName()} branches delete ${branchName}\` then \`${getCliName()} checkout ${branchName}\`.`,
-        ].join("\n"));
-    }
+const handler = async (props) => {
+	const previousBranch = contextBranch(readContextFile(props.contextFile));
+	if (previousBranch) log.info("%s Currently on branch %s", chalk.dim("→"), chalk.cyan.bold(previousBranch));
+	const projectId = await resolveProjectId(props);
+	const { branchId, branchName, created, policyApplied, policyFailure } = await resolveBranchId(props, projectId);
+	const orgId = await resolveOrgId(props, projectId);
+	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);
+	const failure = created && !policyApplied ? await applyPolicyOrDescribeFailure({
+		projectId,
+		branchId,
+		...props.apiKey ? { apiKey: props.apiKey } : {},
+		...props.apiHost ? { apiHost: props.apiHost } : {},
+		...props.color !== void 0 ? { color: props.color } : {}
+	}) : policyFailure;
+	await autoPullEnvAfterPin({
+		...props,
+		projectId,
+		branch: branchId,
+		envPull: props.envPull
+	});
+	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 \`${getCliName()} checkout\` never reconciles a branch that already exists.`,
+		`Fix the cause above, then run \`${getCliName()} 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: \`${getCliName()} branches delete ${branchName}\` then \`${getCliName()} 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.
- */
+* 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);
-    }
+	try {
+		await applyPolicyOnCreate(props);
+		return;
+	} 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. \`${getCliName()} 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);
+	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. \`${getCliName()} 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
+			};
+		}
+		return createCheckoutBranch(props, projectId, picked.name, branches);
+	}
+	const ref = props.id;
+	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
+	};
+	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`).
- */
+* 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 fromPolicy = await createBranchFromPolicyOnCheckout({
+		projectId,
+		branchName: name,
+		...props.apiKey ? { apiKey: props.apiKey } : {},
+		...props.apiHost ? { apiHost: props.apiHost } : {},
+		...props.color !== void 0 ? { 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(", ")}`;
+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.
- */
+* 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;
-    }
+	if (props.orgId) return props.orgId;
+	try {
+		const { data } = await props.apiClient.getProject(projectId);
+		return data.project.org_id ?? void 0;
+	} 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;
+	}
 };
 /**
- * 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.
- */
+* 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 \`${getCliName()} link\` / \`${getCliName()} set-context\`).`;
-    if (isCi() || !process.stdout.isTTY) {
-        throw new Error(missingProjectMessage);
-    }
-    log.error(missingProjectMessage);
-    const { runLink } = await prompts({
-        type: "confirm",
-        name: "runLink",
-        message: `Run \`${getCliName()} 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 \`${getCliName()} 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;
+	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 \`${getCliName()} link\` / \`${getCliName()} set-context\`).`;
+	if (isCi() || !process.stdout.isTTY) throw new Error(missingProjectMessage);
+	log.error(missingProjectMessage);
+	const { runLink } = await prompts({
+		type: "confirm",
+		name: "runLink",
+		message: `Run \`${getCliName()} 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 handler$1({
+		...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 \`${getCliName()} checkout\` once the directory is linked.`);
+	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.
- */
+* 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;
-    }
+	try {
+		return (await fillSingleProject(props)).projectId;
+	} catch (err) {
+		if (isNeonApiError(err)) throw err;
+		log.debug("checkout: could not auto-detect a single project: %s", err instanceof Error ? err.message : String(err));
+		return;
+	}
 };
+//#endregion
+export { builder, checkout_exports, command, describe, handler };