neon 4.5.2 → 4.6.0

package/README.md

@@ -710,6 +710,12 @@ $ neon bootstrap my-app
 
 # Scaffold a specific template into the current directory (no prompts)
 $ neon bootstrap . --template hono
+
+# List templates
+$ neon bootstrap --list-templates
+
+# Machine-readable catalog
+$ neon bootstrap --list-templates --output json
 ```
 
 The target directory must be empty unless you pass `--force` (a lone `.git` is ignored, so a freshly `git init`ed folder is fine). Symlinks and executable bits in the template are preserved.

package/dist/commands/bootstrap.js

@@ -3,8 +3,9 @@ import { isCi } from "../env.js";
 import { log } from "../log.js";
 import { getCliName } from "../utils/cli_name.js";
 import { t as credentialInputs } from "../_chunks/auth_selection-ktL6uoEe.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 { writer } from "../writer.js";
+import { FALLBACK_TEMPLATES, ensureTargetUsable, fetchTemplates, findTemplate, scaffoldTemplate, templateIds } from "../init/bootstrap.js";
+import { 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";
@@ -16,6 +17,7 @@ var bootstrap_exports = /* @__PURE__ */ __exportAll({
 	describe: () => describe,
 	handler: () => handler
 });
+const removedAgent = () => `\`${getCliName()} bootstrap --agent\` was removed. List templates with \`${getCliName()} bootstrap --list-templates --output json\`. Scaffold with \`${getCliName()} bootstrap <directory> --template <id>\` or \`${getCliName()} bootstrap <directory> --default\`.`;
 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", {
@@ -28,7 +30,7 @@ const builder = (argv) => argv.usage("$0 bootstrap [directory] [options]").posit
 	},
 	"list-templates": {
 		alias: ["list", "ls"],
-		describe: "List available templates and exit.",
+		describe: "List available templates and exit. --output json and --output yaml print a machine-readable catalog.",
 		type: "boolean",
 		default: false
 	},
@@ -38,9 +40,8 @@ const builder = (argv) => argv.usage("$0 bootstrap [directory] [options]").posit
 		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
+		hidden: true,
+		type: "boolean"
 	},
 	default: {
 		alias: "y",
@@ -63,20 +64,33 @@ const builder = (argv) => argv.usage("$0 bootstrap [directory] [options]").posit
 		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();
+}).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 --list-templates --output json", "Print the template catalog as JSON").check((argv) => {
+	if (argv.agent === true) throw new Error(removedAgent());
+	return true;
+}).strict();
 const handler = async (props) => {
 	if (props.listTemplates) {
 		const templates = await fetchTemplates();
+		if (props.output === "json" || props.output === "yaml") {
+			writer(props).end(templates.map((t) => ({
+				id: t.id,
+				title: t.title,
+				description: t.description,
+				services: t.services ?? []
+			})), { fields: [
+				"id",
+				"title",
+				"description",
+				"services"
+			] });
+			return;
+		}
 		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);
@@ -163,15 +177,6 @@ const scaffold = async (template, targetDir) => {
 	log.info("Scaffolded %d files into %s.", filesWritten, targetDir);
 	return filesWritten;
 };
-/**
-* 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 inferred = inferPackageManager(targetDir);
 	const defaultPm = resolvePackageManager(targetDir);
@@ -307,103 +312,6 @@ const printNextSteps = (targetDir, pm, opts) => {
 	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);
-	}
-};
-/**
-* 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 === 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`);
-};
-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)
-	};
-};
 const isCurrentDir = (targetDir) => relative(process.cwd(), targetDir) === "";
 /**
 * The path to show the user: the bare relative path for the common
@@ -415,10 +323,6 @@ const displayDir = (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, `'\\''`)}'`;
-};
 const onPromptState = (state) => {
 	if (state.aborted) {
 		process.stdout.write("\x1B[?25h");

package/dist/init/bootstrap.js

@@ -305,12 +305,7 @@ const downloadTemplate = async (template) => {
 	if (files.length === 0) throw new Error(`Template subdirectory "${subdir}" was not found in ${owner}/${repo}@${ref}.`);
 	return files;
 };
-/**
-* A bad caller-supplied input that an agent (or human) can correct: an unknown
-* template id or a non-empty target directory. Carries an `agentCode` so an
-* agent surface can report a precise error code instead of a generic
-* INTERNAL_ERROR, while a human path just surfaces the clear `message`.
-*/
+/** `agentCode` lets programmatic callers branch without parsing human-readable messages. */
 var BootstrapInputError = class extends Error {
 	constructor(message, agentCode) {
 		super(message);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neon",
-  "version": "4.5.2",
+  "version": "4.6.0",
   "description": "CLI tool for Neon, the cloud backend primitives built around Lakebase Postgres",
   "keywords": [
     "neon",