neonctl 2.28.0 → 2.29.0

package/dist/commands/bootstrap.js

@@ -1,77 +1,76 @@
-import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { join, relative, resolve } from 'node:path';
-import chalk from 'chalk';
-import { BootstrapInputError, FALLBACK_TEMPLATES, ensureTargetUsable, fetchTemplates, findTemplate, scaffoldTemplate, templateIds, } from 'neon-init/bootstrap';
-import prompts from 'prompts';
-import which from 'which';
-import { isCi } from '../env.js';
-import { log } from '../log.js';
+import { existsSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import chalk from "chalk";
+import { BootstrapInputError, ensureTargetUsable, FALLBACK_TEMPLATES, fetchTemplates, findTemplate, scaffoldTemplate, templateIds, } from "neon-init/bootstrap";
+import prompts from "prompts";
+import { isCi } from "../env.js";
+import { log } from "../log.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 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', {
+    .usage("$0 bootstrap [directory] [options]")
+    .positional("directory", {
     describe: 'Directory to scaffold into. Use "." for the current directory. Omit to be prompted.',
-    type: 'string',
+    type: "string",
 })
     .options({
     template: {
-        describe: 'Template to use (skips the interactive picker). Run with --list-templates to see available templates.',
-        type: 'string',
+        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',
+    "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',
+        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',
+        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',
+        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',
+        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',
+        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 `neon 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',
+        describe: "Run `neon 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')
+    .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(' · ')}]`
-                : '';
+                ? ` [${t.services.join(" · ")}]`
+                : "";
             process.stdout.write(`${t.id} — ${t.description}${services}\n`);
         }
         return;
@@ -112,7 +111,7 @@ const formatTemplateTitle = (template) => {
     if (!template.services || template.services.length === 0) {
         return template.title;
     }
-    return `${template.title}  ${chalk.dim.italic(template.services.join(' · '))}`;
+    return `${template.title}  ${chalk.dim.italic(template.services.join(" · "))}`;
 };
 const resolveSelectedTemplate = async (props, interactive, templates) => {
     if (props.template) {
@@ -127,7 +126,7 @@ const resolveSelectedTemplate = async (props, interactive, templates) => {
     if (props.default) {
         const fallback = templates[0];
         if (!fallback) {
-            throw new Error('No templates available to scaffold from.');
+            throw new Error("No templates available to scaffold from.");
         }
         return fallback;
     }
@@ -136,9 +135,9 @@ const resolveSelectedTemplate = async (props, interactive, templates) => {
     }
     const { id } = await prompts({
         onState: onPromptState,
-        type: 'select',
-        name: 'id',
-        message: 'Which template would you like to use?',
+        type: "select",
+        name: "id",
+        message: "Which template would you like to use?",
         choices: templates.map((template) => ({
             title: formatTemplateTitle(template),
             value: template.id,
@@ -147,7 +146,7 @@ const resolveSelectedTemplate = async (props, interactive, templates) => {
     });
     const template = findTemplate(templates, id);
     if (!template) {
-        throw new Error('No template selected.');
+        throw new Error("No template selected.");
     }
     return template;
 };
@@ -164,9 +163,9 @@ const resolveTargetDir = async (props, interactive, template) => {
         }
         const { value } = await prompts({
             onState: onPromptState,
-            type: 'text',
-            name: 'value',
-            message: 'Where should we scaffold your project?',
+            type: "text",
+            name: "value",
+            message: "Where should we scaffold your project?",
             initial: defaultDirName(template),
             validate: (input) => input && input.trim().length > 0
                 ? true
@@ -174,9 +173,9 @@ const resolveTargetDir = async (props, interactive, template) => {
         });
         dir = String(value).trim();
     }
-    return resolve(process.cwd(), dir === '.' ? '' : dir);
+    return resolve(process.cwd(), dir === "." ? "" : dir);
 };
-const defaultDirName = (template) => template.source.subdir.split('/').pop() || template.id;
+const defaultDirName = (template) => template.source.subdir.split("/").pop() || template.id;
 /**
  * Download and materialize the template into `targetDir`. The actual
  * download/extract/write lives in the shared `neon-init/bootstrap` core
@@ -190,7 +189,7 @@ const scaffold = async (template, targetDir) => {
             log.warning(message);
         },
     });
-    log.info('Scaffolded %d files into %s.', filesWritten, targetDir);
+    log.info("Scaffolded %d files into %s.", filesWritten, targetDir);
     return filesWritten;
 };
 // ----------------------------------------------------------------------------
@@ -208,11 +207,11 @@ const scaffold = async (template, targetDir) => {
 const runPostScaffoldSteps = async (props, targetDir, interactive) => {
     const detected = detectPackageManager();
     if (props.default) {
-        await runDefaultSteps(props, targetDir, detected ?? 'npm');
+        await runDefaultSteps(props, targetDir, detected ?? "npm");
         return;
     }
     if (!interactive) {
-        printNextSteps(targetDir, detected ?? 'npm', {
+        printNextSteps(targetDir, detected ?? "npm", {
             installed: false,
             suggestLink: true,
         });
@@ -221,15 +220,15 @@ const runPostScaffoldSteps = async (props, targetDir, interactive) => {
     // 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 pm = detected ?? "npm";
     let installed = false;
     if (props.install && (await confirm(installPrompt(detected)))) {
         pm = detected ?? (await selectPackageManager());
-        installed = await runCommand(pm, ['install'], targetDir);
+        installed = await runCommand(pm, ["install"], targetDir);
     }
     if (props.git &&
         !isGitRepo(targetDir) &&
-        (await confirm('Initialize a git repository?'))) {
+        (await confirm("Initialize a git repository?"))) {
         await initGitRepo(targetDir);
     }
     // `neon link` pulls env vars, which loads this project's neon.ts — and that
@@ -240,9 +239,9 @@ const runPostScaffoldSteps = async (props, targetDir, interactive) => {
         if (!installed && hasNeonConfig(targetDir)) {
             log.info("Skipping the Neon link step: `neon link` reads this project's neon.ts " +
                 `to pull env vars, which needs its dependencies. Run \`${pm} install\`, ` +
-                'then `neon link`.');
+                "then `neon link`.");
         }
-        else if (await confirm('Link this project to a Neon project now? (runs neon link)')) {
+        else if (await confirm("Link this project to a Neon project now? (runs neon 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 });
@@ -251,7 +250,9 @@ const runPostScaffoldSteps = async (props, targetDir, interactive) => {
     }
     printNextSteps(targetDir, pm, { installed, suggestLink: true });
 };
-const installPrompt = (detected) => detected ? `Install dependencies with ${detected}?` : 'Install dependencies?';
+const installPrompt = (detected) => detected
+    ? `Install dependencies with ${detected}?`
+    : "Install dependencies?";
 /**
  * `--default` quick start: run install + git init without prompting, honoring
  * --no-install / --no-git. Linking is intentionally skipped — it needs an
@@ -259,20 +260,20 @@ const installPrompt = (detected) => detected ? `Install dependencies with ${dete
  * closing hint instead.
  */
 const runDefaultSteps = async (props, targetDir, pm) => {
-    log.info('Quick start (--default): running setup without prompting.');
+    log.info("Quick start (--default): running setup without prompting.");
     let installed = false;
     if (props.install) {
-        installed = await runCommand(pm, ['install'], targetDir);
+        installed = await runCommand(pm, ["install"], 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 @neondatabase/config). A scaffold
+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
@@ -280,43 +281,18 @@ const hasNeonConfig = (dir) => NEON_CONFIG_FILENAMES.some((name) => existsSync(j
  * 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',
+        type: "confirm",
+        name: "value",
         message,
         initial: true,
     });
     return value === true;
 };
-// npm first so it's the default/preselected choice; the rest follow in rough
-// popularity order.
-const PACKAGE_MANAGERS = ['npm', 'pnpm', 'yarn', 'bun'];
-/**
- * The package manager the CLI was invoked through, read from the
- * `npm_config_user_agent` npm sets for `npm exec`/`npx`, `pnpm dlx`, `yarn
- * dlx`, and `bunx` (so `pnpm dlx neonctl bootstrap` installs with pnpm).
- * Returns undefined when there's nothing to infer from — e.g. a
- * globally-installed `neon`/`neonctl` — so the caller can ask instead of
- * silently assuming npm.
- */
-const detectPackageManager = () => {
-    const ua = process.env.npm_config_user_agent ?? '';
-    if (ua.startsWith('pnpm'))
-        return 'pnpm';
-    if (ua.startsWith('yarn'))
-        return 'yarn';
-    if (ua.startsWith('bun'))
-        return 'bun';
-    if (ua.startsWith('npm'))
-        return 'npm';
-    return undefined;
-};
-/** The package managers actually on PATH, in {@link PACKAGE_MANAGERS} order. */
-const installedPackageManagers = () => PACKAGE_MANAGERS.filter((pm) => which.sync(pm, { nothrow: true }) !== null);
 /**
  * Ask which package manager to install with when we couldn't infer one from the
  * invocation. Offers the managers actually installed (npm preselected); with
@@ -326,45 +302,21 @@ const installedPackageManagers = () => PACKAGE_MANAGERS.filter((pm) => which.syn
 const selectPackageManager = async () => {
     const installed = installedPackageManagers();
     if (installed.length <= 1) {
-        return installed[0] ?? 'npm';
+        return installed[0] ?? "npm";
     }
     const { pm } = await prompts({
         onState: onPromptState,
-        type: 'select',
-        name: 'pm',
-        message: 'Which package manager should we use?',
+        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')),
+        initial: Math.max(0, installed.indexOf("npm")),
     });
-    return pm ?? 'npm';
+    return pm ?? "npm";
 };
-/**
- * Run a command inheriting our stdio so the user sees install / link output
- * live and can answer any prompts the child raises. Resolves to whether it
- * exited cleanly; a non-zero exit is reported but never aborts bootstrap — the
- * scaffold already succeeded, so we let the user retry the step by hand.
- */
-const runCommand = (cmd, args, cwd) => new Promise((resolvePromise) => {
-    // npm/pnpm/yarn ship as .cmd shims on Windows, which need a shell to run.
-    const child = spawn(cmd, args, {
-        cwd,
-        stdio: 'inherit',
-        shell: process.platform === 'win32',
-    });
-    child.on('error', (err) => {
-        log.warning('Could not run `%s %s`: %s', cmd, args.join(' '), err instanceof Error ? err.message : String(err));
-        resolvePromise(false);
-    });
-    child.on('close', (code) => {
-        if (code !== 0) {
-            log.warning('`%s %s` exited with code %d.', cmd, args.join(' '), code);
-        }
-        resolvePromise(code === 0);
-    });
-});
 /**
  * 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
@@ -373,16 +325,18 @@ const runCommand = (cmd, args, cwd) => new Promise((resolvePromise) => {
  * to the target dir, which is where its env pull writes.
  */
 const runNeonLink = async (props, targetDir) => {
-    const args = [process.argv[1], 'link'];
+    const args = [process.argv[1], "link"];
     if (props.apiKey) {
-        args.push('--api-key', props.apiKey);
+        args.push("--api-key", props.apiKey);
     }
-    args.push('--api-host', props.apiHost, '--output', props.output);
+    args.push("--api-host", props.apiHost, "--output", props.output);
     await runCommand(process.execPath, args, targetDir);
 };
 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
@@ -390,19 +344,19 @@ const printScaffolded = (template, targetDir) => {
  * 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:');
+    log.info("");
+    log.info("Next steps:");
     if (!isCurrentDir(targetDir)) {
-        log.info('  cd %s', displayDir(targetDir));
+        log.info("  cd %s", displayDir(targetDir));
     }
     if (!opts.installed) {
-        log.info('  %s install', pm);
+        log.info("  %s install", pm);
     }
     if (opts.suggestLink) {
-        log.info('  neon link');
+        log.info("  neon link");
     }
-    log.info('  See the README to run it.');
-    log.info('');
+    log.info("  See the README to run it.");
+    log.info("");
 };
 const runAgentSafely = async (props) => {
     try {
@@ -425,55 +379,55 @@ 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'}.`,
+            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: `neon bootstrap --agent ${props.directory ? shellArg(props.directory) : '<directory>'} --template <template_id>`,
+            next_command_template: `neon 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');
+        throw new BootstrapInputError(`Unknown template "${props.template}". Available templates: ${templateIds(templates)}.`, "UNKNOWN_TEMPLATE");
     }
     if (props.directory === undefined) {
         emitAgent({
-            status: 'needs_directory',
+            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: `neon bootstrap --agent <directory> --template ${shellArg(template.id)}`,
         });
         return;
     }
-    const targetDir = resolve(process.cwd(), props.directory === '.' ? '' : props.directory);
+    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 runIn = isCurrentDir(targetDir) ? "" : `cd ${shellArg(dir)} && `;
     emitAgent({
-        status: 'scaffolded',
+        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.',
+                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.',
+                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.',
+                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}neon link --agent`,
             },
         ],
@@ -485,17 +439,21 @@ const emitAgent = (response) => {
 };
 const toAgentError = (err) => {
     if (err instanceof BootstrapInputError) {
-        return { status: 'error', code: err.agentCode, message: err.message };
+        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: err.message,
+        };
     }
-    return { status: 'error', code: 'INTERNAL_ERROR', message: String(err) };
+    return { status: "error", code: "INTERNAL_ERROR", message: String(err) };
 };
 // ----------------------------------------------------------------------------
 // Path display helpers
 // ----------------------------------------------------------------------------
-const isCurrentDir = (targetDir) => relative(process.cwd(), targetDir) === '';
+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
@@ -503,10 +461,10 @@ const isCurrentDir = (targetDir) => relative(process.cwd(), targetDir) === '';
  */
 const displayDir = (targetDir) => {
     const rel = relative(process.cwd(), targetDir);
-    if (rel === '') {
-        return '.';
+    if (rel === "") {
+        return ".";
     }
-    return rel.startsWith('..') ? targetDir : rel;
+    return rel.startsWith("..") ? targetDir : rel;
 };
 const shellArg = (value) => {
     if (/^[A-Za-z0-9._:/-]+$/.test(value)) {
@@ -516,8 +474,8 @@ const shellArg = (value) => {
 };
 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);
     }
 };