neon 3.0.0 → 3.1.0

package/dist/commands/bootstrap.js

@@ -1,495 +1,430 @@
+import { __exportAll } from "../_virtual/_rolldown/runtime.js";
+import { isCi } from "../env.js";
+import { log } from "../log.js";
+import { getCliName } from "../utils/cli_name.js";
+import { credentialInputs } from "../_shared/auth_selection.js";
+import { BootstrapInputError, FALLBACK_TEMPLATES, ensureTargetUsable, fetchTemplates, findTemplate, scaffoldTemplate, templateIds } from "../init/bootstrap.js";
+import { DO_NOT_SUBSTITUTE_HINT, formatInstallCommand, inferPackageManager, installArgs, installedPackageManagers, resolvePackageManager, runCommand } from "../utils/package_manager.js";
 import { existsSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
 import chalk from "chalk";
 import prompts from "prompts";
-import { credentialInputs } from "../_shared/auth_selection.js";
-import { isCi } from "../env.js";
-import { BootstrapInputError, ensureTargetUsable, FALLBACK_TEMPLATES, fetchTemplates, findTemplate, scaffoldTemplate, templateIds, } from "../init/bootstrap.js";
-import { log } from "../log.js";
-import { getCliName } from "../utils/cli_name.js";
-import { detectPackageManager, installedPackageManagers, runCommand, } from "../utils/package_manager.js";
-// The directory positional is optional: omitting it in an interactive terminal
-// prompts for one. In a non-interactive context a missing directory is an error.
-export const command = "bootstrap [directory]";
-export const describe = "Scaffold a new project from a Neon starter template";
-export const builder = (argv) => argv
-    .usage("$0 bootstrap [directory] [options]")
-    .positional("directory", {
-    describe: 'Directory to scaffold into. Use "." for the current directory. Omit to be prompted.',
-    type: "string",
-})
-    .options({
-    template: {
-        describe: "Template to use (skips the interactive picker). Run with --list-templates to see available templates.",
-        type: "string",
-    },
-    "list-templates": {
-        alias: ["list", "ls"],
-        describe: "List available templates and exit.",
-        type: "boolean",
-        default: false,
-    },
-    force: {
-        describe: "Scaffold into the target directory even if it is not empty (colliding files are overwritten).",
-        type: "boolean",
-        default: false,
-    },
-    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",
-        default: false,
-    },
-    default: {
-        alias: "y",
-        describe: "Quick start: scaffold the default template (or --template) and run the usual setup (install dependencies, git init) without prompting. Linking is left to you since it needs a project choice.",
-        type: "boolean",
-        default: false,
-    },
-    install: {
-        describe: "Install dependencies after scaffolding. In interactive mode this is offered as a prompt; use --no-install to skip without being asked.",
-        type: "boolean",
-        default: true,
-    },
-    git: {
-        describe: "Initialize a git repository after scaffolding. In interactive mode this is offered as a prompt; use --no-git to skip without being asked.",
-        type: "boolean",
-        default: true,
-    },
-    link: {
-        describe: `Run \`${getCliName()} link\` in the scaffolded directory after installing. In interactive mode this is offered as a prompt; use --no-link to skip without being asked.`,
-        type: "boolean",
-        default: true,
-    },
-})
-    .example("$0 bootstrap my-app", "Create ./my-app from an interactively chosen template")
-    .example("$0 bootstrap . --template hono", "Scaffold the Hono template into the current directory")
-    .example("$0 bootstrap my-app --default", "Quick start: scaffold the default template and run setup without prompting")
-    .example("$0 bootstrap my-app --template hono --agent", "Scaffold without prompting and emit the JSON state machine for AI agents")
-    .strict();
-export const handler = async (props) => {
-    if (props.listTemplates) {
-        const templates = await fetchTemplates();
-        for (const t of templates) {
-            const services = t.services && t.services.length > 0
-                ? ` [${t.services.join(" · ")}]`
-                : "";
-            process.stdout.write(`${t.id} — ${t.description}${services}\n`);
-        }
-        return;
-    }
-    if (props.agent) {
-        await runAgentSafely(props);
-        return;
-    }
-    const templates = await resolveTemplateList(props);
-    // --default is a non-interactive quick start: it fills in the template and
-    // directory and runs setup without asking, so it must not fall into the
-    // prompt path even on a TTY.
-    const interactive = !props.default && Boolean(process.stdout.isTTY) && !isCi();
-    const template = await resolveSelectedTemplate(props, interactive, templates);
-    const targetDir = await resolveTargetDir(props, interactive, template);
-    ensureTargetUsable(targetDir, props.force);
-    await scaffold(template, targetDir);
-    printScaffolded(template, targetDir);
-    await runPostScaffoldSteps(props, targetDir, interactive);
+//#region src/commands/bootstrap.ts
+var bootstrap_exports = /* @__PURE__ */ __exportAll({
+	builder: () => builder,
+	command: () => command,
+	describe: () => describe,
+	handler: () => handler
+});
+const command = "bootstrap [directory]";
+const describe = "Scaffold a new project from a Neon starter template";
+const builder = (argv) => argv.usage("$0 bootstrap [directory] [options]").positional("directory", {
+	describe: "Directory to scaffold into. Use \".\" for the current directory. Omit to be prompted.",
+	type: "string"
+}).options({
+	template: {
+		describe: "Template to use (skips the interactive picker). Run with --list-templates to see available templates.",
+		type: "string"
+	},
+	"list-templates": {
+		alias: ["list", "ls"],
+		describe: "List available templates and exit.",
+		type: "boolean",
+		default: false
+	},
+	force: {
+		describe: "Scaffold into the target directory even if it is not empty (colliding files are overwritten).",
+		type: "boolean",
+		default: false
+	},
+	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",
+		default: false
+	},
+	default: {
+		alias: "y",
+		describe: "Quick start: scaffold the default template (or --template) and run the usual setup (install dependencies, git init) without prompting. Linking is left to you since it needs a project choice.",
+		type: "boolean",
+		default: false
+	},
+	install: {
+		describe: "Install dependencies after scaffolding. In interactive mode this is offered as a prompt; use --no-install to skip without being asked.",
+		type: "boolean",
+		default: true
+	},
+	git: {
+		describe: "Initialize a git repository after scaffolding. In interactive mode this is offered as a prompt; use --no-git to skip without being asked.",
+		type: "boolean",
+		default: true
+	},
+	link: {
+		describe: `Run \`${getCliName()} link\` in the scaffolded directory after installing. In interactive mode this is offered as a prompt; use --no-link to skip without being asked.`,
+		type: "boolean",
+		default: true
+	}
+}).example("$0 bootstrap my-app", "Create ./my-app from an interactively chosen template").example("$0 bootstrap . --template hono", "Scaffold the Hono template into the current directory").example("$0 bootstrap my-app --default", "Quick start: scaffold the default template and run setup without prompting").example("$0 bootstrap my-app --template hono --agent", "Scaffold without prompting and emit the JSON state machine for AI agents").strict();
+const handler = async (props) => {
+	if (props.listTemplates) {
+		const templates = await fetchTemplates();
+		for (const t of templates) {
+			const services = t.services && t.services.length > 0 ? ` [${t.services.join(" · ")}]` : "";
+			process.stdout.write(`${t.id} — ${t.description}${services}\n`);
+		}
+		return;
+	}
+	if (props.agent) {
+		await runAgentSafely(props);
+		return;
+	}
+	const templates = await resolveTemplateList(props);
+	const interactive = !props.default && Boolean(process.stdout.isTTY) && !isCi();
+	const template = await resolveSelectedTemplate(props, interactive, templates);
+	const targetDir = await resolveTargetDir(props, interactive, template);
+	ensureTargetUsable(targetDir, props.force);
+	await scaffold(template, targetDir);
+	printScaffolded(template, targetDir);
+	await runPostScaffoldSteps(props, targetDir, interactive);
 };
 /**
- * The template list to choose from. When --template is given we try the
- * built-in fallback list first to avoid a network round-trip, only fetching the
- * remote manifest if the id isn't one of the defaults.
- */
-const resolveTemplateList = async (props) => props.template && findTemplate(FALLBACK_TEMPLATES, props.template)
-    ? FALLBACK_TEMPLATES
-    : fetchTemplates();
+* The template list to choose from. When --template is given we try the
+* built-in fallback list first to avoid a network round-trip, only fetching the
+* remote manifest if the id isn't one of the defaults.
+*/
+const resolveTemplateList = async (props) => props.template && findTemplate(FALLBACK_TEMPLATES, props.template) ? FALLBACK_TEMPLATES : fetchTemplates();
 /**
- * The picker label for a template: the title first, then the Neon services it
- * uses as a dim, italic suffix, e.g. "Hono API …  Postgres · Functions". The
- * suffix is styled with chalk.dim (and italic) only — never a foreground color —
- * so it survives the cyan/underline `prompts` paints over the focused row: dim
- * and italic reset with their own SGRs, leaving the row's color and underline
- * intact. Descriptions are intentionally omitted to keep the picker uncluttered.
- */
+* The picker label for a template: the title first, then the Neon services it
+* uses as a dim, italic suffix, e.g. "Hono API …  Postgres · Functions". The
+* suffix is styled with chalk.dim (and italic) only — never a foreground color —
+* so it survives the cyan/underline `prompts` paints over the focused row: dim
+* and italic reset with their own SGRs, leaving the row's color and underline
+* intact. Descriptions are intentionally omitted to keep the picker uncluttered.
+*/
 const formatTemplateTitle = (template) => {
-    if (!template.services || template.services.length === 0) {
-        return template.title;
-    }
-    return `${template.title}  ${chalk.dim.italic(template.services.join(" · "))}`;
+	if (!template.services || template.services.length === 0) return template.title;
+	return `${template.title}  ${chalk.dim.italic(template.services.join(" · "))}`;
 };
 const resolveSelectedTemplate = async (props, interactive, templates) => {
-    if (props.template) {
-        const template = findTemplate(templates, props.template);
-        if (!template) {
-            throw new Error(`Unknown template "${props.template}". Available templates: ${templateIds(templates)}.`);
-        }
-        return template;
-    }
-    // --default with no --template falls back to the first (default) template so
-    // a bare `neon bootstrap my-app --default` works end to end.
-    if (props.default) {
-        const fallback = templates[0];
-        if (!fallback) {
-            throw new Error("No templates available to scaffold from.");
-        }
-        return fallback;
-    }
-    if (!interactive) {
-        throw new Error(`No template selected. Re-run in an interactive terminal to pick one, or pass --template <id>. Available templates: ${templateIds(templates)}.`);
-    }
-    const { id } = await prompts({
-        onState: onPromptState,
-        type: "select",
-        name: "id",
-        message: "Which template would you like to use?",
-        choices: templates.map((template) => ({
-            title: formatTemplateTitle(template),
-            value: template.id,
-        })),
-        initial: 0,
-    });
-    const template = findTemplate(templates, id);
-    if (!template) {
-        throw new Error("No template selected.");
-    }
-    return template;
+	if (props.template) {
+		const template = findTemplate(templates, props.template);
+		if (!template) throw new Error(`Unknown template "${props.template}". Available templates: ${templateIds(templates)}.`);
+		return template;
+	}
+	if (props.default) {
+		const fallback = templates[0];
+		if (!fallback) throw new Error("No templates available to scaffold from.");
+		return fallback;
+	}
+	if (!interactive) throw new Error(`No template selected. Re-run in an interactive terminal to pick one, or pass --template <id>. Available templates: ${templateIds(templates)}.`);
+	const { id } = await prompts({
+		onState: onPromptState,
+		type: "select",
+		name: "id",
+		message: "Which template would you like to use?",
+		choices: templates.map((template) => ({
+			title: formatTemplateTitle(template),
+			value: template.id
+		})),
+		initial: 0
+	});
+	const template = findTemplate(templates, id);
+	if (!template) throw new Error("No template selected.");
+	return template;
 };
 const resolveTargetDir = async (props, interactive, template) => {
-    let dir = props.directory;
-    if (dir === undefined) {
-        // --default supplies a directory (the template's name) so the quick start
-        // needs nothing but a template.
-        if (props.default) {
-            return resolve(process.cwd(), defaultDirName(template));
-        }
-        if (!interactive) {
-            throw new Error(`No target directory given. Pass one, e.g. \`${getCliName()} bootstrap my-app\` (or "." for the current directory).`);
-        }
-        const { value } = await prompts({
-            onState: onPromptState,
-            type: "text",
-            name: "value",
-            message: "Where should we scaffold your project?",
-            initial: defaultDirName(template),
-            validate: (input) => input && input.trim().length > 0
-                ? true
-                : 'Enter a directory (use "." for the current directory).',
-        });
-        dir = String(value).trim();
-    }
-    return resolve(process.cwd(), dir === "." ? "" : dir);
+	let dir = props.directory;
+	if (dir === void 0) {
+		if (props.default) return resolve(process.cwd(), defaultDirName(template));
+		if (!interactive) throw new Error(`No target directory given. Pass one, e.g. \`${getCliName()} bootstrap my-app\` (or "." for the current directory).`);
+		const { value } = await prompts({
+			onState: onPromptState,
+			type: "text",
+			name: "value",
+			message: "Where should we scaffold your project?",
+			initial: defaultDirName(template),
+			validate: (input) => input && input.trim().length > 0 ? true : "Enter a directory (use \".\" for the current directory)."
+		});
+		dir = String(value).trim();
+	}
+	return resolve(process.cwd(), dir === "." ? "" : dir);
 };
 const defaultDirName = (template) => template.source.subdir.split("/").pop() || template.id;
 /**
- * Download and materialize the template into `targetDir`. The actual
- * download/extract/write lives in `src/init/bootstrap.ts`, shared with `neon init`
- * (exec-bit and symlink fidelity, graceful symlink fallback); here we just
- * frame it with progress logging. Returns the number of files written.
- */
+* Download and materialize the template into `targetDir`. The actual
+* download/extract/write lives in `src/init/bootstrap.ts`, shared with `neon init`
+* (exec-bit and symlink fidelity, graceful symlink fallback); here we just
+* frame it with progress logging. Returns the number of files written.
+*/
 const scaffold = async (template, targetDir) => {
-    log.info('Fetching template "%s" from GitHub…', template.id);
-    const filesWritten = await scaffoldTemplate(template, targetDir, {
-        onWarn: (message) => {
-            log.warning(message);
-        },
-    });
-    log.info("Scaffolded %d files into %s.", filesWritten, targetDir);
-    return filesWritten;
+	log.info("Fetching template \"%s\" from GitHub…", template.id);
+	const filesWritten = await scaffoldTemplate(template, targetDir, { onWarn: (message) => {
+		log.warning(message);
+	} });
+	log.info("Scaffolded %d files into %s.", filesWritten, targetDir);
+	return filesWritten;
 };
-// ----------------------------------------------------------------------------
-// Post-scaffold steps (install dependencies, git init, link to a Neon project)
-// ----------------------------------------------------------------------------
 /**
- * After a human scaffold, offer the things you almost always do next: install
- * dependencies, initialize a git repo, and link the directory to a Neon
- * project. In an interactive terminal each is a y/n prompt (skippable up front
- * with --no-install / --no-git / --no-link); `--default` runs install + git
- * without asking; otherwise we just print the manual steps so nothing runs
- * behind the user's back. Agent mode never reaches here — it returns these as
- * structured `next_steps` instead (see {@link runAgent}).
- */
+* After a human scaffold, offer the things you almost always do next: install
+* dependencies, initialize a git repo, and link the directory to a Neon
+* project. In an interactive terminal each is a y/n prompt (skippable up front
+* with --no-install / --no-git / --no-link); `--default` runs install + git
+* without asking; otherwise we just print the manual steps so nothing runs
+* behind the user's back. Agent mode never reaches here — it returns these as
+* structured `next_steps` instead (see {@link runAgent}).
+*/
 const runPostScaffoldSteps = async (props, targetDir, interactive) => {
-    const detected = detectPackageManager();
-    if (props.default) {
-        await runDefaultSteps(props, targetDir, detected ?? "npm");
-        return;
-    }
-    if (!interactive) {
-        printNextSteps(targetDir, detected ?? "npm", {
-            installed: false,
-            suggestLink: true,
-        });
-        return;
-    }
-    // The package manager used for the install (and shown in the closing hint).
-    // When we couldn't infer it from the invocation we ask, so a globally
-    // installed `neon` doesn't silently force npm on a bun/pnpm user.
-    let pm = detected ?? "npm";
-    let installed = false;
-    if (props.install && (await confirm(installPrompt(detected)))) {
-        pm = detected ?? (await selectPackageManager());
-        installed = await runCommand(pm, ["install"], targetDir);
-    }
-    if (props.git &&
-        !isGitRepo(targetDir) &&
-        (await confirm("Initialize a git repository?"))) {
-        await initGitRepo(targetDir);
-    }
-    // `neon link` pulls env vars, which loads this project's neon.ts — and that
-    // evaluation needs the dependencies installed. So when deps weren't installed
-    // and the scaffold ships a neon.ts, skip the link prompt (it would just fail)
-    // and tell the user how to finish by hand.
-    if (props.link) {
-        if (!installed && hasNeonConfig(targetDir)) {
-            log.info(`Skipping the Neon link step: \`${getCliName()} link\` reads this project's neon.ts ` +
-                `to pull env vars, which needs its dependencies. Run \`${pm} install\`, ` +
-                `then \`${getCliName()} link\`.`);
-        }
-        else if (await confirm(`Link this project to a Neon project now? (runs ${getCliName()} link)`)) {
-            await runNeonLink(props, targetDir);
-            // link prints its own summary (and pulls env), so end with just the run hint.
-            printNextSteps(targetDir, pm, { installed, suggestLink: false });
-            return;
-        }
-    }
-    printNextSteps(targetDir, pm, { installed, suggestLink: true });
+	const inferred = inferPackageManager(targetDir);
+	const defaultPm = resolvePackageManager(targetDir);
+	if (props.default) {
+		await runDefaultSteps(props, targetDir, defaultPm);
+		return;
+	}
+	if (!interactive) {
+		printNextSteps(targetDir, defaultPm, {
+			installed: false,
+			suggestLink: true
+		});
+		return;
+	}
+	let pm = defaultPm;
+	let installed = false;
+	if (props.install && await confirm(installPrompt(inferred))) {
+		pm = inferred ?? await selectPackageManager();
+		installed = await runCommand(pm, installArgs(pm), targetDir);
+	}
+	if (props.git && !isGitRepo(targetDir) && await confirm("Initialize a git repository?")) await initGitRepo(targetDir);
+	if (props.link) {
+		if (!installed && hasNeonConfig(targetDir)) log.info(`Skipping the Neon link step: \`${getCliName()} link\` reads this project's neon.ts to pull env vars, which needs its dependencies. Run \`${formatInstallCommand(pm)}\`, then \`${getCliName()} link\`.`);
+		else if (await confirm(`Link this project to a Neon project now? (runs ${getCliName()} link)`)) {
+			await runNeonLink(props, targetDir);
+			printNextSteps(targetDir, pm, {
+				installed,
+				suggestLink: false
+			});
+			return;
+		}
+	}
+	printNextSteps(targetDir, pm, {
+		installed,
+		suggestLink: true
+	});
 };
-const installPrompt = (detected) => detected
-    ? `Install dependencies with ${detected}?`
-    : "Install dependencies?";
+const installPrompt = (inferred) => inferred ? `Install dependencies with ${inferred}?` : "Install dependencies?";
 /**
- * `--default` quick start: run install + git init without prompting, honoring
- * --no-install / --no-git. Linking is intentionally skipped — it needs an
- * org/project choice we can't make non-interactively — so we point at it in the
- * closing hint instead.
- */
+* `--default` quick start: run install + git init without prompting, honoring
+* --no-install / --no-git. Linking is intentionally skipped — it needs an
+* org/project choice we can't make non-interactively — so we point at it in the
+* closing hint instead.
+*/
 const runDefaultSteps = async (props, targetDir, pm) => {
-    log.info("Quick start (--default): running setup without prompting.");
-    let installed = false;
-    if (props.install) {
-        installed = await runCommand(pm, ["install"], targetDir);
-    }
-    if (props.git && !isGitRepo(targetDir)) {
-        await initGitRepo(targetDir);
-    }
-    printNextSteps(targetDir, pm, { installed, suggestLink: true });
+	log.info("Quick start (--default): running setup without prompting.");
+	let installed = false;
+	if (props.install) installed = await runCommand(pm, installArgs(pm), targetDir);
+	if (props.git && !isGitRepo(targetDir)) await initGitRepo(targetDir);
+	printNextSteps(targetDir, pm, {
+		installed,
+		suggestLink: true
+	});
 };
 const isGitRepo = (dir) => existsSync(join(dir, ".git"));
-// Config filenames the runtime loads (mirrors @neon/config). A scaffold
-// that ships one makes `neon link`'s env pull evaluate it — which needs deps.
-const NEON_CONFIG_FILENAMES = ["neon.ts", "neon.mts", "neon.js", "neon.mjs"];
+const NEON_CONFIG_FILENAMES = [
+	"neon.ts",
+	"neon.mts",
+	"neon.js",
+	"neon.mjs"
+];
 const hasNeonConfig = (dir) => NEON_CONFIG_FILENAMES.some((name) => existsSync(join(dir, name)));
 /**
- * Initialize a git repository in the scaffolded directory. Just `git init` — we
- * deliberately don't auto-commit, both to avoid failing on a machine with no
- * git identity configured and to leave the first commit to the user.
- */
+* Initialize a git repository in the scaffolded directory. Just `git init` — we
+* deliberately don't auto-commit, both to avoid failing on a machine with no
+* git identity configured and to leave the first commit to the user.
+*/
 const initGitRepo = async (dir) => {
-    await runCommand("git", ["init"], dir);
+	await runCommand("git", ["init"], dir);
 };
 const confirm = async (message) => {
-    const { value } = await prompts({
-        onState: onPromptState,
-        type: "confirm",
-        name: "value",
-        message,
-        initial: true,
-    });
-    return value === true;
+	const { value } = await prompts({
+		onState: onPromptState,
+		type: "confirm",
+		name: "value",
+		message,
+		initial: true
+	});
+	return value === true;
 };
 /**
- * Ask which package manager to install with when we couldn't infer one from the
- * invocation. Offers the managers actually installed (npm preselected); with
- * one or none installed there's nothing to choose, so it returns that one (or
- * npm) without prompting. A cancelled prompt falls back to npm.
- */
+* Ask which package manager to install with when we couldn't infer one from the
+* invocation. Offers the managers actually installed (npm preselected); with
+* one or none installed there's nothing to choose, so it returns that one (or
+* npm) without prompting. A cancelled prompt falls back to npm.
+*/
 const selectPackageManager = async () => {
-    const installed = installedPackageManagers();
-    if (installed.length <= 1) {
-        return installed[0] ?? "npm";
-    }
-    const { pm } = await prompts({
-        onState: onPromptState,
-        type: "select",
-        name: "pm",
-        message: "Which package manager should we use?",
-        choices: installed.map((manager) => ({
-            title: manager,
-            value: manager,
-        })),
-        initial: Math.max(0, installed.indexOf("npm")),
-    });
-    return pm ?? "npm";
+	const installed = installedPackageManagers();
+	if (installed.length <= 1) return installed[0] ?? "npm";
+	const { pm } = await prompts({
+		onState: onPromptState,
+		type: "select",
+		name: "pm",
+		message: "Which package manager should we use?",
+		choices: installed.map((manager) => ({
+			title: manager,
+			value: manager
+		})),
+		initial: Math.max(0, installed.indexOf("npm"))
+	});
+	return pm ?? "npm";
 };
 /**
- * Re-invoke this same CLI as `neon link` inside the scaffolded directory, so the
- * new project's `.neon` context (and pulled `.env`) land in the right place and
- * link's own interactive picker drives org/project/branch selection. Re-execing
- * (rather than calling the handler in-process) keeps link running with `cwd` set
- * to the target dir, which is where its env pull writes.
- */
+* Re-invoke this same CLI as `neon link` inside the scaffolded directory, so the
+* new project's `.neon` context (and pulled `.env`) land in the right place and
+* link's own interactive picker drives org/project/branch selection. Re-execing
+* (rather than calling the handler in-process) keeps link running with `cwd` set
+* to the target dir, which is where its env pull writes.
+*/
 const runNeonLink = async (props, targetDir) => {
-    const args = [process.argv[1], "link"];
-    // Forward how to authenticate, never the credential itself. A key on the child's argv is
-    // visible to anything that can list processes, and `runCommand` prints the whole argument
-    // list when the command fails — so a failed link would put the key in the log too.
-    // Forwarding the selection also keeps the child on the same account: without `--profile` it
-    // would resolve its own, and `--config-dir` was never forwarded at all.
-    if (props.configDir) {
-        args.push("--config-dir", props.configDir);
-    }
-    if (props.profile) {
-        args.push("--profile", props.profile);
-    }
-    args.push("--api-host", props.apiHost, "--output", props.output);
-    // An explicit `--api-key` has nowhere else to go — the child cannot re-resolve a flag we
-    // were given — so it travels in the environment, which neither `ps` nor our own logging
-    // exposes. A profile needs none of this; the child reads the credential itself.
-    const explicitKey = props.profile ? "" : credentialInputs().apiKeyFlag;
-    await runCommand(process.execPath, args, targetDir, explicitKey ? { NEON_API_KEY: explicitKey } : undefined);
+	const args = [process.argv[1], "link"];
+	if (props.configDir) args.push("--config-dir", props.configDir);
+	if (props.profile) args.push("--profile", props.profile);
+	args.push("--api-host", props.apiHost, "--output", props.output);
+	const explicitKey = props.profile ? "" : credentialInputs().apiKeyFlag;
+	await runCommand(process.execPath, args, targetDir, explicitKey ? { NEON_API_KEY: explicitKey } : void 0);
 };
 const printScaffolded = (template, targetDir) => {
-    log.info("");
-    log.info('Done. Scaffolded "%s" into %s.', template.title, isCurrentDir(targetDir)
-        ? "the current directory"
-        : displayDir(targetDir));
+	log.info("");
+	log.info("Done. Scaffolded \"%s\" into %s.", template.title, isCurrentDir(targetDir) ? "the current directory" : displayDir(targetDir));
 };
 /**
- * The closing "Next steps" hint. Skips `cd` for the current directory, omits
- * the install line once deps are in, and only nudges `neon link` when linking
- * wasn't already offered/run — so the user never sees a step they just did.
- */
+* The closing "Next steps" hint. Skips `cd` for the current directory, omits
+* the install line once deps are in, and only nudges `neon link` when linking
+* wasn't already offered/run — so the user never sees a step they just did.
+*/
 const printNextSteps = (targetDir, pm, opts) => {
-    log.info("");
-    log.info("Next steps:");
-    if (!isCurrentDir(targetDir)) {
-        log.info("  cd %s", displayDir(targetDir));
-    }
-    if (!opts.installed) {
-        log.info("  %s install", pm);
-    }
-    if (opts.suggestLink) {
-        log.info(`  ${getCliName()} link`);
-    }
-    log.info("  See the README to run it.");
-    log.info("");
+	log.info("");
+	log.info("Next steps:");
+	if (!isCurrentDir(targetDir)) log.info("  cd %s", displayDir(targetDir));
+	if (!opts.installed) log.info("  %s", formatInstallCommand(pm));
+	if (opts.suggestLink) log.info(`  ${getCliName()} link`);
+	log.info("  See the README to run it.");
+	log.info("");
 };
 const runAgentSafely = async (props) => {
-    try {
-        await runAgent(props);
-    }
-    catch (err) {
-        emitAgent(toAgentError(err));
-        process.exit(1);
-    }
+	try {
+		await runAgent(props);
+	} catch (err) {
+		emitAgent(toAgentError(err));
+		process.exit(1);
+	}
 };
 /**
- * The `--agent` flow: resolve what the flags determine and emit one JSON object
- * describing either the next input needed (`needs_template` / `needs_directory`)
- * or the terminal result (`scaffolded`). Unlike interactive mode it never
- * prompts and never runs install/git/link itself — those come back as structured
- * `next_steps` so the agent can confirm with the user and run them (the link
- * step chains into `neon link --agent`).
- */
+* The `--agent` flow: resolve what the flags determine and emit one JSON object
+* describing either the next input needed (`needs_template` / `needs_directory`)
+* or the terminal result (`scaffolded`). Unlike interactive mode it never
+* prompts and never runs install/git/link itself — those come back as structured
+* `next_steps` so the agent can confirm with the user and run them (the link
+* step chains into `neon link --agent`).
+*/
 const runAgent = async (props) => {
-    if (!props.template) {
-        const templates = await fetchTemplates();
-        emitAgent({
-            status: "needs_template",
-            instruction: `Ask the user which template to scaffold, then re-run the next_command_template with the chosen --template value${props.directory ? "" : " and a target directory"}.`,
-            options: templates.map((template) => ({
-                id: template.id,
-                title: template.title,
-                description: template.description,
-                ...(template.services ? { services: template.services } : {}),
-            })),
-            next_command_template: `${getCliName()} bootstrap --agent ${props.directory ? shellArg(props.directory) : "<directory>"} --template <template_id>`,
-        });
-        return;
-    }
-    const templates = await resolveTemplateList(props);
-    const template = findTemplate(templates, props.template);
-    if (!template) {
-        throw new BootstrapInputError(`Unknown template "${props.template}". Available templates: ${templateIds(templates)}.`, "UNKNOWN_TEMPLATE");
-    }
-    if (props.directory === undefined) {
-        emitAgent({
-            status: "needs_directory",
-            instruction: 'Ask the user which directory to scaffold into (use "." for the current directory), then re-run the next_command_template with it.',
-            next_command_template: `${getCliName()} bootstrap --agent <directory> --template ${shellArg(template.id)}`,
-        });
-        return;
-    }
-    const targetDir = resolve(process.cwd(), props.directory === "." ? "" : props.directory);
-    ensureTargetUsable(targetDir, props.force);
-    const filesWritten = await scaffold(template, targetDir);
-    const dir = displayDir(targetDir);
-    const runIn = isCurrentDir(targetDir) ? "" : `cd ${shellArg(dir)} && `;
-    emitAgent({
-        status: "scaffolded",
-        directory: targetDir,
-        template: { id: template.id, title: template.title },
-        files_written: filesWritten,
-        next_steps: [
-            {
-                action: "install_dependencies",
-                instruction: "Ask the user whether to install dependencies, then run this in the project directory.",
-                command: `${runIn}npm install`,
-            },
-            {
-                action: "initialize_git",
-                instruction: "Ask the user whether to initialize a git repository in the project directory.",
-                command: `${runIn}git init`,
-            },
-            {
-                action: "link_neon_project",
-                instruction: "Ask the user whether to link the project to a Neon project now. This runs the link state machine — follow its JSON output for the next step.",
-                command: `${runIn}${getCliName()} link --agent`,
-            },
-        ],
-        message: `Scaffolded "${template.title}" (${filesWritten} files) into ${dir}. Offer the next_steps to the user: install dependencies, initialize git, then link a Neon project.`,
-    });
+	if (!props.template) {
+		const templates = await fetchTemplates();
+		emitAgent({
+			status: "needs_template",
+			instruction: `Ask the user which template to scaffold, then re-run the next_command_template with the chosen --template value${props.directory ? "" : " and a target directory"}.`,
+			options: templates.map((template) => ({
+				id: template.id,
+				title: template.title,
+				description: template.description,
+				...template.services ? { services: template.services } : {}
+			})),
+			next_command_template: `${getCliName()} bootstrap --agent ${props.directory ? shellArg(props.directory) : "<directory>"} --template <template_id>`
+		});
+		return;
+	}
+	const templates = await resolveTemplateList(props);
+	const template = findTemplate(templates, props.template);
+	if (!template) throw new BootstrapInputError(`Unknown template "${props.template}". Available templates: ${templateIds(templates)}.`, "UNKNOWN_TEMPLATE");
+	if (props.directory === void 0) {
+		emitAgent({
+			status: "needs_directory",
+			instruction: "Ask the user which directory to scaffold into (use \".\" for the current directory), then re-run the next_command_template with it.",
+			next_command_template: `${getCliName()} bootstrap --agent <directory> --template ${shellArg(template.id)}`
+		});
+		return;
+	}
+	const targetDir = resolve(process.cwd(), props.directory === "." ? "" : props.directory);
+	ensureTargetUsable(targetDir, props.force);
+	const filesWritten = await scaffold(template, targetDir);
+	const dir = displayDir(targetDir);
+	const runIn = isCurrentDir(targetDir) ? "" : `cd ${shellArg(dir)} && `;
+	const installPm = resolvePackageManager(targetDir);
+	emitAgent({
+		status: "scaffolded",
+		directory: targetDir,
+		template: {
+			id: template.id,
+			title: template.title
+		},
+		files_written: filesWritten,
+		next_steps: [
+			{
+				action: "install_dependencies",
+				instruction: `Ask the user whether to install dependencies, then run this in the project directory. ${DO_NOT_SUBSTITUTE_HINT}`,
+				command: `${runIn}${formatInstallCommand(installPm)}`
+			},
+			{
+				action: "initialize_git",
+				instruction: "Ask the user whether to initialize a git repository in the project directory.",
+				command: `${runIn}git init`
+			},
+			{
+				action: "link_neon_project",
+				instruction: "Ask the user whether to link the project to a Neon project now. This runs the link state machine — follow its JSON output for the next step.",
+				command: `${runIn}${getCliName()} link --agent`
+			}
+		],
+		message: `Scaffolded "${template.title}" (${filesWritten} files) into ${dir}. Offer the next_steps to the user: install dependencies, initialize git, then link a Neon project.`
+	});
 };
 const emitAgent = (response) => {
-    process.stdout.write(`${JSON.stringify(response, null, 2)}\n`);
+	process.stdout.write(`${JSON.stringify(response, null, 2)}\n`);
 };
 const toAgentError = (err) => {
-    if (err instanceof BootstrapInputError) {
-        return { status: "error", code: err.agentCode, message: err.message };
-    }
-    if (err instanceof Error) {
-        return {
-            status: "error",
-            code: "INTERNAL_ERROR",
-            message: err.message,
-        };
-    }
-    return { status: "error", code: "INTERNAL_ERROR", message: String(err) };
+	if (err instanceof BootstrapInputError) return {
+		status: "error",
+		code: err.agentCode,
+		message: err.message
+	};
+	if (err instanceof Error) return {
+		status: "error",
+		code: "INTERNAL_ERROR",
+		message: err.message
+	};
+	return {
+		status: "error",
+		code: "INTERNAL_ERROR",
+		message: String(err)
+	};
 };
-// ----------------------------------------------------------------------------
-// Path display helpers
-// ----------------------------------------------------------------------------
 const isCurrentDir = (targetDir) => relative(process.cwd(), targetDir) === "";
 /**
- * The path to show the user: the bare relative path for the common
- * `bootstrap my-app` case, the absolute path when the target sits outside the
- * cwd (a deep `../../..` is noise), and "." for the current directory.
- */
+* The path to show the user: the bare relative path for the common
+* `bootstrap my-app` case, the absolute path when the target sits outside the
+* cwd (a deep `../../..` is noise), and "." for the current directory.
+*/
 const displayDir = (targetDir) => {
-    const rel = relative(process.cwd(), targetDir);
-    if (rel === "") {
-        return ".";
-    }
-    return rel.startsWith("..") ? targetDir : rel;
+	const rel = relative(process.cwd(), targetDir);
+	if (rel === "") return ".";
+	return rel.startsWith("..") ? targetDir : rel;
 };
 const shellArg = (value) => {
-    if (/^[A-Za-z0-9._:/-]+$/.test(value)) {
-        return value;
-    }
-    return `'${value.replace(/'/g, `'\\''`)}'`;
+	if (/^[A-Za-z0-9._:/-]+$/.test(value)) return value;
+	return `'${value.replace(/'/g, `'\\''`)}'`;
 };
 const onPromptState = (state) => {
-    if (state.aborted) {
-        process.stdout.write("\x1B[?25h");
-        process.stdout.write("\n");
-        process.exit(1);
-    }
+	if (state.aborted) {
+		process.stdout.write("\x1B[?25h");
+		process.stdout.write("\n");
+		process.exit(1);
+	}
 };
+//#endregion
+export { bootstrap_exports, builder, command, describe, handler };