neon 2.44.0 → 2.46.0

package/dist/index.js

@@ -1,4 +1,3 @@
-import { basename } from "node:path";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 import { analyticsMiddleware, closeAnalytics, getAnalyticsEventProperties, initAnalyticsClientMiddleware, sendError, trackEvent, } from "./analytics.js";
@@ -13,6 +12,7 @@ import { isNetworkError, matchErrorCode, NETWORK_ERROR_MESSAGE, } from "./errors
 import { showHelp } from "./help.js";
 import { log } from "./log.js";
 import pkg from "./pkg.js";
+import { getCliName } from "./utils/cli_name.js";
 import { fillInArgs, resolveApiKeyFromEnv } from "./utils/middlewares.js";
 const NO_SUBCOMMANDS_VERBS = [
     // `api <path>` has a handler but no subcommands (like `status`), so the
@@ -159,7 +159,7 @@ builder = builder
     .group("version", "Global options:")
     .alias("version", "v")
     .completion()
-    .scriptName(basename(process.argv[1]) === "neon" ? "neon" : "neonctl")
+    .scriptName(getCliName())
     .epilog("For more information, visit https://neon.com/docs/reference/neon-cli")
     .wrap(null)
     .fail(false);

package/dist/init/agents.js

@@ -0,0 +1,127 @@
+/**
+ * All agents that can be configured via neon-init.
+ * Aligns with add-mcp's supported agents table.
+ * https://github.com/neondatabase/add-mcp#supported-agents
+ */
+export const ALL_CONFIGURABLE_AGENTS = [
+    {
+        editor: "Cursor",
+        addMcpId: "cursor",
+        hint: "Neon Local Connect extension",
+    },
+    {
+        editor: "VS Code",
+        addMcpId: "vscode",
+        hint: "Neon Local Connect extension",
+    },
+    { editor: "Claude CLI", addMcpId: "claude-code", hint: "MCP Server" },
+    {
+        editor: "Claude Desktop",
+        addMcpId: "claude-desktop",
+        hint: "MCP Server",
+    },
+    { editor: "Codex", addMcpId: "codex", hint: "MCP Server" },
+    { editor: "OpenCode", addMcpId: "opencode", hint: "MCP Server" },
+    { editor: "Antigravity", addMcpId: "antigravity", hint: "MCP Server" },
+    { editor: "Cline", addMcpId: "cline", hint: "MCP Server" },
+    { editor: "Cline CLI", addMcpId: "cline-cli", hint: "MCP Server" },
+    { editor: "Gemini CLI", addMcpId: "gemini-cli", hint: "MCP Server" },
+    {
+        editor: "GitHub Copilot CLI",
+        addMcpId: "github-copilot-cli",
+        hint: "MCP Server",
+    },
+    { editor: "Goose", addMcpId: "goose", hint: "MCP Server" },
+    { editor: "MCPorter", addMcpId: "mcporter", hint: "MCP Server" },
+    { editor: "Zed", addMcpId: "zed", hint: "MCP Server" },
+];
+export function getAddMcpAgentId(editor) {
+    const agent = ALL_CONFIGURABLE_AGENTS.find((a) => a.editor === editor);
+    if (!agent) {
+        throw new Error(`No add-mcp agent ID found for editor: ${editor}`);
+    }
+    return agent.addMcpId;
+}
+/**
+ * Maps a raw agent identifier (as reported by agents or passed via --agent)
+ * to the add-mcp compatible agent ID.
+ *
+ * This handles aliases like "copilot" → "vscode", "claude" → "claude-code", etc.
+ */
+const AGENT_ALIAS_TO_MCP_ID = {
+    cursor: "cursor",
+    copilot: "vscode",
+    "github-copilot": "vscode",
+    "vs-code": "vscode",
+    vscode: "vscode",
+    claude: "claude-code",
+    "claude-code": "claude-code",
+    "claude-desktop": "claude-desktop",
+    codex: "codex",
+    opencode: "opencode",
+    antigravity: "antigravity",
+    cline: "cline",
+    "cline-cli": "cline-cli",
+    "gemini-cli": "gemini-cli",
+    gemini: "gemini-cli",
+    goose: "goose",
+    windsurf: "windsurf",
+    "github-copilot-cli": "github-copilot-cli",
+    mcporter: "mcporter",
+    zed: "zed",
+};
+export function resolveAddMcpAgentId(rawAgent) {
+    const resolved = AGENT_ALIAS_TO_MCP_ID[rawAgent.toLowerCase()];
+    if (!resolved) {
+        throw new Error(`Unknown agent: "${rawAgent}". Supported agents: ${Object.keys(AGENT_ALIAS_TO_MCP_ID).join(", ")}`);
+    }
+    return resolved;
+}
+/**
+ * Maps a raw agent identifier to the skills CLI agent name.
+ */
+export function getSkillsAgentName(agent) {
+    switch (agent.toLowerCase()) {
+        case "cursor":
+            return "cursor";
+        case "copilot":
+        case "vscode":
+        case "vs-code":
+        case "github-copilot":
+            return "github-copilot";
+        case "claude":
+        case "claude-code":
+            return "claude-code";
+        case "codex":
+            return "codex";
+        case "opencode":
+            return "opencode";
+        case "antigravity":
+            return "antigravity";
+        case "cline":
+            return "cline";
+        case "gemini-cli":
+            return "gemini-cli";
+        case "goose":
+            return "goose";
+        case "claude-desktop":
+            return "claude-code";
+        case "cline-cli":
+            return "cline";
+        case "gemini":
+            return "gemini-cli";
+        case "windsurf":
+            return "windsurf";
+        case "github-copilot-cli":
+            return "github-copilot";
+        case "mcporter":
+            return "mcporter";
+        case "zed":
+            return "zed";
+        default:
+            // Fall back to "cursor" as a safe default — skills CLI uses the
+            // agent name to pick the output directory (.agents/skills, .cursor/skills, etc.)
+            // and "cursor" uses .agents/skills which works for all agents.
+            return "cursor";
+    }
+}

package/dist/init/auth.js

@@ -0,0 +1,77 @@
+import { log } from "@clack/prompts";
+import { execa } from "execa";
+import { inspectCredentials, interpretCredentials, } from "../_shared/credentials.js";
+import { resolveConfigFile } from "../_shared/paths.js";
+import { DEFAULT_PROFILE } from "../_shared/profiles.js";
+/**
+ * Ensures neonctl is authenticated by running a command that triggers auth if needed
+ * This will automatically start the OAuth flow if the user isn't already authenticated
+ */
+export async function ensureNeonctlAuth(options) {
+    const quiet = options?.json === true;
+    // If already authenticated (e.g. ran in a terminal before), we can proceed
+    const existingToken = await getNeonctlAccessToken();
+    if (existingToken)
+        return true;
+    try {
+        // Use execa to authenticate with neonctl
+        await execa("npx", ["-y", "neonctl", "me"], {
+            // Shows OAuth URL and prompts to the user
+            stdio: "inherit",
+            // Unset CI so neonctl doesn't refuse to open the browser (e.g. when run from agent chat)
+            env: { ...process.env, CI: undefined },
+        });
+        return true;
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : "Unknown error";
+        if (!quiet) {
+            if (msg.includes("interactive auth") || msg.includes("CI")) {
+                log.error("Auth requires an interactive terminal. Run neon init in your system terminal (outside the chat) to sign in.");
+            }
+            else {
+                log.error(`Authentication failed: ${msg}`);
+            }
+        }
+        return false;
+    }
+}
+/**
+ * Checks whether neonctl has stored OAuth credentials.
+ */
+export async function isAuthenticated() {
+    const token = await getNeonctlAccessToken();
+    return token !== null;
+}
+/**
+ * The credential the Neon CLI has stored, or `null` when there is none.
+ *
+ * Shares the reader with `neon` and `@neon/env` rather than keeping a copy — the inline path
+ * resolution this replaced was the third implementation of "where is the config directory", and
+ * it also looked only for `access_token`, so an account signed in with an API key read as not
+ * authenticated and got sent to a browser. See `shared/cli-core/README.md`.
+ *
+ * `null` means *absent*, and only absent. A file that exists and cannot be read throws: this
+ * value decides whether to start a browser sign-in, and a sign-in overwrites the file it could
+ * not read — as a different account, if a different one is chosen. Catching every error here
+ * made a damaged credential indistinguishable from a fresh machine.
+ */
+async function getNeonctlAccessToken() {
+    const { path } = resolveConfigFile("credentials.json");
+    const read = inspectCredentials(path);
+    if (read.kind === "absent")
+        return null;
+    if (read.kind === "unusable") {
+        throw new Error(`${read.reason}. Replace it deliberately with \`neon profile create ${DEFAULT_PROFILE} --force\`, or delete the file.`);
+    }
+    // `neon init` has no profile selection — it reads the default credential and refuses
+    // when one is named, so `DEFAULT` is the only profile this can ever be about.
+    const credential = interpretCredentials(read.credentials, {
+        path,
+        profile: DEFAULT_PROFILE,
+    });
+    if (credential.kind === "api_key")
+        return credential.apiKey;
+    const token = read.credentials.access_token;
+    return typeof token === "string" && token.trim() !== "" ? token : null;
+}

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 = "";