neon 2.45.0 → 2.46.0

package/dist/init/bootstrap.js

@@ -0,0 +1,448 @@
+import { chmodSync, existsSync, lstatSync, mkdirSync, readdirSync, rmSync, statSync, symlinkSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { gunzipSync } from "fflate";
+import YAML from "yaml";
+/** Default features when a template doesn't specify `requires`. */
+const DEFAULT_REQUIRES = ["database"];
+/**
+ * Hardcoded fallback used when every remote manifest source is unreachable.
+ * Kept in sync with `neondatabase/examples/bootstrap.yaml` (the source of
+ * truth) so that, even fully offline from the manifest, the picker still offers
+ * the full set of starters rather than a single template.
+ */
+export const FALLBACK_TEMPLATES = [
+    {
+        id: "hono",
+        title: "REST API",
+        description: "A Hono REST API on Neon Functions, backed by Lakebase Postgres via Drizzle.",
+        tools: ["Hono", "Drizzle"],
+        services: ["Postgres", "Functions"],
+        requires: ["database", "functions"],
+        source: {
+            owner: "neondatabase",
+            repo: "examples",
+            ref: "main",
+            subdir: "with-hono",
+        },
+    },
+    {
+        id: "ai-sdk",
+        title: "Image-generation agent",
+        description: "A Vercel AI SDK agent that streams chat through the Neon AI Gateway and stores generated images in Neon object storage, indexed in Postgres via Drizzle.",
+        tools: ["AI SDK", "Drizzle"],
+        services: ["Postgres", "Functions", "Object Storage", "AI Gateway"],
+        requires: ["database", "functions", "object-storage", "ai-gateway"],
+        source: {
+            owner: "neondatabase",
+            repo: "examples",
+            ref: "main",
+            subdir: "with-ai-sdk",
+        },
+    },
+    {
+        id: "mastra",
+        title: "Personal-assistant agent",
+        description: "A Mastra agent that streams chat through the Neon AI Gateway and uses Mastra Memory on Lakebase Postgres to remember you across threads.",
+        tools: ["Mastra", "Mastra Memory"],
+        services: ["Postgres", "Functions", "AI Gateway"],
+        requires: ["database", "functions", "ai-gateway"],
+        source: {
+            owner: "neondatabase",
+            repo: "examples",
+            ref: "main",
+            subdir: "with-mastra",
+        },
+    },
+];
+export const templateIds = (templates) => templates.map((t) => t.id).join(", ");
+export const findTemplate = (templates, id) => templates.find((t) => t.id === id);
+const githubToken = () => process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN ?? "";
+// A token is never required for public templates, but we forward it when
+// present so the same code path works behind proxies that authenticate, and
+// (in future) for private template repos.
+const downloadHeaders = () => ({
+    // GitHub rejects a request with no User-Agent; the value is free-form and this
+    // one only has to name the client honestly.
+    "User-Agent": "neon",
+    ...(githubToken() ? { Authorization: `Bearer ${githubToken()}` } : {}),
+});
+// The codeload host is overridable so the e2e tests can point the downloader at
+// a local server (the same trick `--api-host` uses to redirect the Neon API).
+const codeloadBase = () => process.env.NEON_BOOTSTRAP_GITHUB_CODELOAD ?? "https://codeload.github.com";
+const isRecord = (value) => typeof value === "object" && value !== null;
+/**
+ * Normalize a manifest entry's string list (`tools` or `services`) into a clean
+ * array. Tolerant by design: a missing or non-array value yields `undefined`,
+ * and non-string/blank items are dropped, so a malformed list never sinks an
+ * otherwise-valid template (it just renders without that detail).
+ */
+const parseStringList = (value) => {
+    if (!Array.isArray(value))
+        return undefined;
+    const items = value.filter((item) => typeof item === "string" && item.trim() !== "");
+    return items.length > 0 ? items : undefined;
+};
+// ---------------------------------------------------------------------------
+// Remote template manifest
+// ---------------------------------------------------------------------------
+// Primary manifest host is neon.com (CDN-backed, no GitHub rate limiting), with
+// the raw GitHub copy as a fallback and the hardcoded list as the last resort.
+// A single env override (used by tests) short-circuits the chain.
+const NEON_MANIFEST_URL = "https://neon.com/bootstrap/templates.yaml";
+const GITHUB_RAW_MANIFEST_URL = "https://raw.githubusercontent.com/neondatabase/examples/main/bootstrap.yaml";
+function manifestUrls() {
+    const override = process.env.NEON_BOOTSTRAP_MANIFEST_URL;
+    if (override)
+        return [override];
+    return [NEON_MANIFEST_URL, GITHUB_RAW_MANIFEST_URL];
+}
+export function parseManifest(text) {
+    const data = YAML.parse(text);
+    if (!isRecord(data) || !Array.isArray(data.templates)) {
+        throw new Error('Invalid bootstrap manifest: missing "templates" array.');
+    }
+    const templates = [];
+    for (const item of data.templates) {
+        if (!isRecord(item) ||
+            typeof item.id !== "string" ||
+            typeof item.title !== "string" ||
+            typeof item.description !== "string" ||
+            !isRecord(item.source) ||
+            typeof item.source.owner !== "string" ||
+            typeof item.source.repo !== "string" ||
+            typeof item.source.ref !== "string" ||
+            typeof item.source.subdir !== "string") {
+            continue;
+        }
+        // Parse requires — accept a string array, default to ["database"].
+        const requires = Array.isArray(item.requires) &&
+            item.requires.every((r) => typeof r === "string")
+            ? item.requires
+            : DEFAULT_REQUIRES;
+        const tools = parseStringList(item.tools);
+        const services = parseStringList(item.services);
+        templates.push({
+            id: item.id,
+            title: item.title,
+            description: item.description,
+            ...(tools ? { tools } : {}),
+            ...(services ? { services } : {}),
+            requires,
+            source: {
+                owner: item.source.owner,
+                repo: item.source.repo,
+                ref: item.source.ref,
+                subdir: item.source.subdir,
+            },
+        });
+    }
+    return templates;
+}
+/**
+ * Fetch the template manifest, trying each source in {@link manifestUrls} in
+ * order and returning the first that yields a non-empty template list. Falls
+ * back to the hardcoded list when every source is unreachable or empty, so the
+ * picker never fails just because a host is down.
+ */
+export async function fetchTemplates() {
+    for (const url of manifestUrls()) {
+        try {
+            const res = await fetch(url, {
+                headers: downloadHeaders(),
+                signal: AbortSignal.timeout(10000),
+            });
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            const templates = parseManifest(await res.text());
+            if (templates.length > 0)
+                return templates;
+        }
+        catch {
+            // Try the next source.
+        }
+    }
+    return FALLBACK_TEMPLATES;
+}
+const TAR_BLOCK = 512;
+const readTarString = (buf, offset, length) => {
+    let end = offset;
+    const max = offset + length;
+    while (end < max && buf[end] !== 0)
+        end++;
+    return buf.toString("utf8", offset, end);
+};
+const readTarOctal = (buf, offset, length) => {
+    const text = readTarString(buf, offset, length).trim();
+    if (text === "")
+        return 0;
+    const value = parseInt(text, 8);
+    return Number.isNaN(value) ? 0 : value;
+};
+const isZeroBlock = (buf, offset) => {
+    for (let i = offset; i < offset + TAR_BLOCK; i++) {
+        if (buf[i] !== 0)
+            return false;
+    }
+    return true;
+};
+/**
+ * Parse pax extended-header records ("<len> <key>=<value>\n"). GitHub uses
+ * these for the global header and for any path that doesn't fit the legacy
+ * 100-byte name field, so we must honor at least `path` and `linkpath`.
+ */
+const parsePaxRecords = (data) => {
+    const records = {};
+    let pos = 0;
+    const text = data.toString("utf8");
+    while (pos < text.length) {
+        const space = text.indexOf(" ", pos);
+        if (space === -1)
+            break;
+        const len = parseInt(text.slice(pos, space), 10);
+        if (Number.isNaN(len) || len <= 0)
+            break;
+        const record = text.slice(space + 1, pos + len - 1); // drop trailing "\n"
+        const eq = record.indexOf("=");
+        if (eq !== -1)
+            records[record.slice(0, eq)] = record.slice(eq + 1);
+        pos += len;
+    }
+    return records;
+};
+/**
+ * Decode a (decompressed) tar archive into its file/symlink entries. Pure and
+ * dependency-free so it can be unit tested without touching the network.
+ * Handles the ustar `prefix` field, pax extended headers (type 'x'/'g'), and
+ * GNU long-name/long-link headers (type 'L'/'K') so deep template paths and
+ * long symlink targets round-trip correctly.
+ */
+export const parseTar = (buf) => {
+    const entries = [];
+    // Overrides carried from a preceding pax/GNU header to the next real entry.
+    let overridePath;
+    let overrideLink;
+    let offset = 0;
+    while (offset + TAR_BLOCK <= buf.length) {
+        if (isZeroBlock(buf, offset))
+            break;
+        let name = readTarString(buf, offset, 100);
+        const mode = readTarOctal(buf, offset + 100, 8);
+        const size = readTarOctal(buf, offset + 124, 12);
+        const typeByte = buf[offset + 156];
+        const type = typeByte === 0 ? "0" : String.fromCharCode(typeByte);
+        let linkname = readTarString(buf, offset + 157, 100);
+        const magic = readTarString(buf, offset + 257, 6);
+        if (magic.startsWith("ustar")) {
+            const prefix = readTarString(buf, offset + 345, 155);
+            if (prefix !== "")
+                name = `${prefix}/${name}`;
+        }
+        offset += TAR_BLOCK;
+        const data = buf.subarray(offset, offset + size);
+        offset += Math.ceil(size / TAR_BLOCK) * TAR_BLOCK;
+        if (type === "x") {
+            const records = parsePaxRecords(data);
+            if (records.path !== undefined)
+                overridePath = records.path;
+            if (records.linkpath !== undefined)
+                overrideLink = records.linkpath;
+            continue;
+        }
+        if (type === "g") {
+            // Global pax header (e.g. GitHub's comment block): not per-entry state.
+            continue;
+        }
+        if (type === "L" || type === "K") {
+            const longValue = data.toString("utf8").replace(/\0+$/, "");
+            if (type === "L")
+                overridePath = longValue;
+            else
+                overrideLink = longValue;
+            continue;
+        }
+        if (overridePath !== undefined)
+            name = overridePath;
+        if (overrideLink !== undefined)
+            linkname = overrideLink;
+        overridePath = undefined;
+        overrideLink = undefined;
+        entries.push({ name, type, mode, linkname, data: Buffer.from(data) });
+    }
+    return entries;
+};
+/**
+ * Map decoded tar entries to the files under `subdir`, with the top-level
+ * archive directory and the `subdir/` prefix stripped from each path. Pure so
+ * it can be unit tested. Directory and other non-regular entries are dropped —
+ * writing files re-creates their parent directories.
+ */
+export const selectTemplateFiles = (entries, subdir) => {
+    const prefix = `${subdir.replace(/^\/+|\/+$/g, "")}/`;
+    const files = [];
+    for (const entry of entries) {
+        // codeload wraps everything in a single top-level dir ("<repo>-<ref>/");
+        // strip that first segment to get the repo-relative path.
+        const slash = entry.name.indexOf("/");
+        if (slash === -1)
+            continue;
+        const repoPath = entry.name.slice(slash + 1);
+        if (!repoPath.startsWith(prefix))
+            continue;
+        const path = repoPath.slice(prefix.length);
+        if (path === "")
+            continue;
+        if (entry.type === "2") {
+            files.push({ kind: "symlink", path, target: entry.linkname });
+        }
+        else if (entry.type === "0" || entry.type === "7") {
+            files.push({
+                kind: "file",
+                path,
+                bytes: entry.data,
+                executable: (entry.mode & 0o111) !== 0,
+            });
+        }
+        // Directories ('5') and any other node types are intentionally skipped.
+    }
+    return files;
+};
+const tarballUrl = (template) => {
+    const { owner, repo, ref } = template.source;
+    return `${codeloadBase()}/${owner}/${repo}/tar.gz/${ref}`;
+};
+const friendlyGithubError = (status, url) => {
+    if (status === 404) {
+        return new Error(`GitHub returned 404 for ${url}. The template repo or ref may have moved.`);
+    }
+    if (status === 403 || status === 429) {
+        return new Error(`GitHub rate limited the template download (${url}). Set a GITHUB_TOKEN environment variable to raise the limit, then retry.`);
+    }
+    return new Error(`GitHub returned HTTP ${status} for ${url}.`);
+};
+/**
+ * Download a template and resolve it to the exact set of files to write. The
+ * entire subtree is captured in one tarball request, so the copy is atomically
+ * consistent: a push to the template repo mid-download cannot produce a
+ * mismatched checkout (unlike fetching a file list and then each blob).
+ */
+export const downloadTemplate = async (template) => {
+    const url = tarballUrl(template);
+    let gzipped;
+    try {
+        const res = await fetch(url, {
+            headers: downloadHeaders(),
+            signal: AbortSignal.timeout(30000),
+        });
+        if (!res.ok)
+            throw friendlyGithubError(res.status, url);
+        gzipped = Buffer.from(await res.arrayBuffer());
+    }
+    catch (err) {
+        throw err instanceof Error ? err : new Error(String(err));
+    }
+    let tar;
+    try {
+        tar = Buffer.from(gunzipSync(new Uint8Array(gzipped)));
+    }
+    catch (err) {
+        throw new Error(`Failed to decompress the template archive from ${url}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const { owner, repo, ref, subdir } = template.source;
+    const files = selectTemplateFiles(parseTar(tar), subdir);
+    if (files.length === 0) {
+        throw new Error(`Template subdirectory "${subdir}" was not found in ${owner}/${repo}@${ref}.`);
+    }
+    return files;
+};
+// ---------------------------------------------------------------------------
+// Target validation + scaffolding to disk
+// ---------------------------------------------------------------------------
+/**
+ * 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`.
+ */
+export class BootstrapInputError extends Error {
+    constructor(message, agentCode) {
+        super(message);
+        this.name = "BootstrapInputError";
+        this.agentCode = agentCode;
+    }
+}
+/**
+ * Ensure `dir` is safe to scaffold into: it must be missing, or an empty
+ * directory (a lone `.git` is ignored so you can scaffold into a freshly
+ * `git init`ed folder). `force` allows scaffolding into a non-empty directory,
+ * overwriting colliding files. Throws a {@link BootstrapInputError} otherwise.
+ */
+export const ensureTargetUsable = (dir, force) => {
+    if (!existsSync(dir))
+        return;
+    if (!statSync(dir).isDirectory()) {
+        throw new BootstrapInputError(`Target ${dir} already exists and is not a directory.`, "TARGET_NOT_DIRECTORY");
+    }
+    const contents = readdirSync(dir).filter((name) => name !== ".git");
+    if (contents.length > 0 && !force) {
+        throw new BootstrapInputError(`Target directory ${dir} is not empty. Use --force to scaffold into it anyway (colliding files will be overwritten), or choose an empty directory.`, "TARGET_NOT_EMPTY");
+    }
+};
+const isSymlink = (path) => {
+    try {
+        return lstatSync(path).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+};
+const errnoCode = (err) => {
+    if (typeof err === "object" &&
+        err !== null &&
+        "code" in err &&
+        typeof err.code === "string") {
+        return err.code;
+    }
+    return undefined;
+};
+const writeSymlink = (dest, target, onWarn) => {
+    if (isSymlink(dest))
+        rmSync(dest, { force: true });
+    try {
+        symlinkSync(target, dest);
+    }
+    catch (err) {
+        // Windows refuses symlinks without elevated rights / developer mode. The
+        // template still works for most tooling if we drop a regular file holding
+        // the link target, so we degrade gracefully instead of failing the copy.
+        if (errnoCode(err) === "EPERM" || process.platform === "win32") {
+            onWarn?.(`Could not create symlink ${dest} -> ${target}; wrote it as a regular file instead.`);
+            writeFileSync(dest, target);
+            return;
+        }
+        throw err;
+    }
+};
+/**
+ * Download `template` and materialize its files into `targetDir`, creating
+ * parent directories, preserving executable bits, and recreating symlinks
+ * (with a graceful regular-file fallback on platforms that disallow them).
+ * Returns the number of files written. The caller is responsible for any
+ * target validation ({@link ensureTargetUsable}) and user-facing progress.
+ */
+export const scaffoldTemplate = async (template, targetDir, options = {}) => {
+    const files = await downloadTemplate(template);
+    mkdirSync(targetDir, { recursive: true });
+    for (const file of files) {
+        const dest = join(targetDir, file.path);
+        mkdirSync(dirname(dest), { recursive: true });
+        if (file.kind === "symlink") {
+            writeSymlink(dest, file.target, options.onWarn);
+        }
+        else {
+            writeFileSync(dest, file.bytes);
+            if (file.executable)
+                chmodSync(dest, 0o755);
+        }
+    }
+    return files.length;
+};

package/dist/init/build_config.js

@@ -0,0 +1,2 @@
+// Auto-generated by scripts/set-vsx-gallery.mjs — do not edit
+export const INTERNAL_VSX_GALLERY = "";

package/dist/init/detect_agent.js

@@ -0,0 +1,108 @@
+import { existsSync } from "node:fs";
+/**
+ * Detects the IDE/editor the terminal is running in, regardless of which
+ * agent is active. Used for extension installation — the extension goes
+ * into the IDE, not the agent.
+ *
+ * Returns an Editor-compatible string: "Cursor", "VS Code", "Windsurf", or null.
+ */
+export function detectIde() {
+    const env = process.env;
+    // Cursor: check explicit Cursor env vars (set in extension host context)
+    if (env.TERM_PROGRAM === "cursor" ||
+        env.CURSOR_TRACE_ID !== undefined ||
+        env.CURSOR_EXTENSION_HOST_ROLE !== undefined ||
+        env.CURSOR_LAYOUT !== undefined ||
+        env.CURSOR_SPAWNED_BY_EXTENSION_ID !== undefined) {
+        return "Cursor";
+    }
+    // Cursor: check app paths in env vars (reliable from terminal context)
+    if (env.GIT_ASKPASS?.includes("Cursor.app") ||
+        env.VSCODE_GIT_ASKPASS_NODE?.includes("Cursor.app") ||
+        env.GIT_ASKPASS?.includes("cursor") ||
+        env.VSCODE_GIT_ASKPASS_NODE?.includes("cursor")) {
+        return "Cursor";
+    }
+    // Windsurf
+    if (env.TERM_PROGRAM === "windsurf") {
+        return "Windsurf";
+    }
+    // At this point we know we're in a VS Code-like environment if any
+    // VSCODE_ env vars are set. But is it actually Cursor with generic env vars?
+    if (env.TERM_PROGRAM === "vscode" ||
+        env.VSCODE_PID !== undefined ||
+        env.VSCODE_CWD !== undefined) {
+        // Check any remaining env vars that might contain "cursor" (case-insensitive)
+        // This catches VSCODE_IPC_HOOK_CLI, PATH additions, etc.
+        const envValues = Object.values(env).join("\n").toLowerCase();
+        if (envValues.includes("cursor.app") ||
+            envValues.includes("/cursor/")) {
+            return "Cursor";
+        }
+        // If only Cursor is installed (not VS Code), it must be Cursor
+        if (isCursorInstalled() && !isVSCodeInstalled()) {
+            return "Cursor";
+        }
+        return "VS Code";
+    }
+    return null;
+}
+export function isCursorInstalled() {
+    if (process.platform === "darwin") {
+        return existsSync("/Applications/Cursor.app");
+    }
+    if (process.platform === "linux") {
+        return existsSync("/usr/share/cursor") || existsSync("/usr/bin/cursor");
+    }
+    if (process.platform === "win32") {
+        const localAppData = process.env.LOCALAPPDATA || "";
+        return (existsSync(`${localAppData}\\Programs\\Cursor\\Cursor.exe`) ||
+            existsSync(`${localAppData}\\cursor\\Cursor.exe`));
+    }
+    return false;
+}
+export function isVSCodeInstalled() {
+    if (process.platform === "darwin") {
+        return existsSync("/Applications/Visual Studio Code.app");
+    }
+    if (process.platform === "linux") {
+        return existsSync("/usr/share/code") || existsSync("/usr/bin/code");
+    }
+    if (process.platform === "win32") {
+        const localAppData = process.env.LOCALAPPDATA || "";
+        const programFiles = process.env.PROGRAMFILES || "C:\\Program Files";
+        return (existsSync(`${localAppData}\\Programs\\Microsoft VS Code\\Code.exe`) || existsSync(`${programFiles}\\Microsoft VS Code\\Code.exe`));
+    }
+    return false;
+}
+/**
+ * Detects which agent/IDE is running the CLI from environment variables.
+ * Returns the add-mcp compatible agent ID (e.g. "cursor", "claude-code").
+ *
+ * Delegates IDE detection to detectIde() to avoid duplicating Cursor/VS Code
+ * heuristics, then checks for agent-specific env vars.
+ */
+export function detectAgent() {
+    const env = process.env;
+    // Agent-specific env vars (checked first — these are unambiguous)
+    if (env.CLAUDECODE === "1" ||
+        env.CLAUDE_CODE === "1" ||
+        env.CLAUDE_CLI === "1") {
+        return "claude-code";
+    }
+    if (env.CODEX === "1")
+        return "codex";
+    if (env.CLINE === "1")
+        return "cline";
+    // Fall back to IDE detection (Cursor, VS Code, Windsurf)
+    const ide = detectIde();
+    if (ide) {
+        const IDE_TO_AGENT = {
+            Cursor: "cursor",
+            "VS Code": "vscode",
+            Windsurf: "windsurf",
+        };
+        return IDE_TO_AGENT[ide] ?? null;
+    }
+    return null;
+}

package/dist/init/editors.js

@@ -0,0 +1,62 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { execa } from "execa";
+/**
+ * Gets VS Code's global config directory based on the platform
+ */
+export function getVSCodeGlobalConfigDir(homeDir) {
+    const platform = process.platform;
+    if (platform === "darwin") {
+        // macOS: ~/Library/Application Support/Code/User
+        return resolve(homeDir, "Library", "Application Support", "Code", "User");
+    }
+    if (platform === "linux") {
+        // Linux: ~/.config/Code/User
+        return resolve(homeDir, ".config", "Code", "User");
+    }
+    if (platform === "win32") {
+        // Windows: %APPDATA%\Code\User
+        const appData = process.env.APPDATA;
+        if (appData) {
+            return resolve(appData, "Code", "User");
+        }
+    }
+    return null;
+}
+/**
+ * Checks if Claude CLI is installed
+ */
+async function isClaudeCLIInstalled() {
+    try {
+        await execa("claude", ["--version"], {
+            stdio: "ignore",
+            timeout: 5000,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Detects which editors are installed on the system
+ */
+export async function detectAvailableEditors(homeDir) {
+    const editors = [];
+    // Check for Cursor (global config directory)
+    const cursorDir = resolve(homeDir, ".cursor");
+    if (existsSync(cursorDir)) {
+        editors.push("Cursor");
+    }
+    // Check if VS Code's global config directory exists
+    const vscodeGlobalDir = getVSCodeGlobalConfigDir(homeDir);
+    if (vscodeGlobalDir && existsSync(vscodeGlobalDir)) {
+        editors.push("VS Code");
+    }
+    // Check for Claude CLI by running the command
+    const claudeInstalled = await isClaudeCLIInstalled();
+    if (claudeInstalled) {
+        editors.push("Claude CLI");
+    }
+    return editors;
+}

package/dist/init/enrich_output.js

@@ -0,0 +1,71 @@
+/**
+ * Converts a phase's `args` (e.g. ["neon-auth", "--json", "--setup"]) into the
+ * `neon init --agent --data` invocation that reaches the same handler.
+ */
+function argsToCommand(args) {
+    const data = {};
+    let i = 0;
+    // First non-flag arg is the subcommand → step
+    if (args.length > 0 && !args[0].startsWith("-")) {
+        data.step = args[0];
+        i = 1;
+    }
+    while (i < args.length) {
+        const arg = args[i];
+        if (arg.startsWith("--")) {
+            const key = arg
+                .slice(2)
+                .replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+            if (key === "json") {
+                i += 1;
+                continue;
+            }
+            const next = args[i + 1];
+            if (next !== undefined && !next.startsWith("-")) {
+                data[key] = next;
+                i += 2;
+            }
+            else {
+                data[key] = true;
+                i += 1;
+            }
+        }
+        else {
+            i += 1;
+        }
+    }
+    return `neon init --agent --data '${JSON.stringify(data)}'`;
+}
+/**
+ * Walks a phase response object and:
+ * 1. Replaces `args` arrays with `command` strings (neon init --data format)
+ * 2. Renames `run_neon_init` → `run_shell_command`
+ * 3. Adds a description to finalize steps
+ */
+export function enrichResponse(obj) {
+    if (obj === null || typeof obj !== "object")
+        return obj;
+    if (Array.isArray(obj))
+        return obj.map(enrichResponse);
+    const record = obj;
+    const result = {};
+    for (const [key, value] of Object.entries(record)) {
+        result[key] = enrichResponse(value);
+    }
+    // Replace args with command in run_neon_init actions and responseMapping entries
+    if (Array.isArray(result.args)) {
+        result.command = argsToCommand(result.args);
+        delete result.args;
+    }
+    // Rename run_neon_init → run_shell_command so agents don't infer subcommand patterns
+    if (result.type === "run_neon_init") {
+        result.type = "run_shell_command";
+        // Help agents understand finalize is the terminal step
+        if (typeof result.command === "string" &&
+            result.command.includes('"step":"finalize"')) {
+            result.description =
+                "Run this command to complete the setup. This is the final step — do not run any other neon init commands after this.";
+        }
+    }
+    return result;
+}