neonctl 2.26.7 → 2.27.0

package/commands/bootstrap.js

@@ -1,12 +1,12 @@
 import { spawn } from 'node:child_process';
-import { chmodSync, existsSync, lstatSync, mkdirSync, readdirSync, rmSync, statSync, symlinkSync, writeFileSync, } from 'node:fs';
-import { dirname, join, relative, resolve } from 'node:path';
+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 { FALLBACK_TEMPLATES, downloadTemplate, fetchTemplates, findTemplate, templateIds, } from '../utils/bootstrap.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]';
@@ -178,70 +178,20 @@ const resolveTargetDir = async (props, interactive, template) => {
 };
 const defaultDirName = (template) => template.source.subdir.split('/').pop() || template.id;
 /**
- * A bad user-supplied input that an agent (or human) can correct: an unknown
- * template id or a non-empty target directory. Carries an `agentCode` so
- * `--agent` mode reports a precise `status: error` code instead of a generic
- * INTERNAL_ERROR, while the human path just surfaces the clear `message`.
+ * Download and materialize the template into `targetDir`. The actual
+ * download/extract/write lives in the shared `neon-init/bootstrap` core
+ * (exec-bit and symlink fidelity, graceful symlink fallback); here we just
+ * frame it with progress logging. Returns the number of files written.
  */
-class BootstrapInputError extends Error {
-    constructor(message, agentCode) {
-        super(message);
-        this.name = 'BootstrapInputError';
-        this.agentCode = agentCode;
-    }
-}
-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');
-    }
-    // A lone `.git` is ignored so you can scaffold into a freshly `git init`ed
-    // (otherwise empty) directory without reaching for --force.
-    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 scaffold = async (template, targetDir) => {
     log.info('Fetching template "%s" from GitHub…', template.id);
-    const files = await downloadTemplate(template);
-    mkdirSync(targetDir, { recursive: true });
-    log.info('Scaffolding %d files into %s…', files.length, targetDir);
-    for (const file of files) {
-        const dest = join(targetDir, file.path);
-        mkdirSync(dirname(dest), { recursive: true });
-        if (file.kind === 'symlink') {
-            writeSymlink(dest, file.target);
-        }
-        else {
-            writeFileSync(dest, file.bytes);
-            if (file.executable) {
-                chmodSync(dest, 0o755);
-            }
-        }
-    }
-    return files.length;
-};
-const writeSymlink = (dest, target) => {
-    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') {
-            log.warning('Could not create symlink %s -> %s; wrote it as a regular file instead.', dest, target);
-            writeFileSync(dest, target);
-            return;
-        }
-        throw err;
-    }
+    const filesWritten = await scaffoldTemplate(template, targetDir, {
+        onWarn: (message) => {
+            log.warning(message);
+        },
+    });
+    log.info('Scaffolded %d files into %s.', filesWritten, targetDir);
+    return filesWritten;
 };
 // ----------------------------------------------------------------------------
 // Post-scaffold steps (install dependencies, git init, link to a Neon project)
@@ -558,23 +508,6 @@ const displayDir = (targetDir) => {
     }
     return rel.startsWith('..') ? targetDir : rel;
 };
-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 shellArg = (value) => {
     if (/^[A-Za-z0-9._:/-]+$/.test(value)) {
         return value;

package/package.json

@@ -5,7 +5,7 @@
     "url": "git+ssh://git@github.com/neondatabase/neonctl.git"
   },
   "type": "module",
-  "version": "2.26.7",
+  "version": "2.27.0",
   "description": "CLI tool for NeonDB Cloud management",
   "main": "index.js",
   "author": "NeonDB",
@@ -71,7 +71,7 @@
     "cliui": "8.0.1",
     "diff": "5.2.0",
     "fflate": "^0.8.3",
-    "neon-init": "0.17.2",
+    "neon-init": "0.19.0",
     "open": "10.1.0",
     "openid-client": "6.8.1",
     "pg-protocol": "^1.14.0",

package/utils/bootstrap.js

@@ -1,364 +0,0 @@
-import axios, { isAxiosError } from 'axios';
-import { gunzipSync } from 'fflate';
-import YAML from 'yaml';
-import { log } from '../log.js';
-/**
- * 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: 'Hono API (Drizzle, Neon Postgres) on Neon Functions',
-        description: 'A Hono API using Drizzle ORM and Neon Postgres, ready to deploy as a Neon Function.',
-        services: ['Postgres', 'Functions'],
-        source: {
-            owner: 'neondatabase',
-            repo: 'examples',
-            ref: 'main',
-            subdir: 'with-hono',
-        },
-    },
-    {
-        id: 'ai-sdk',
-        title: 'AI SDK agent (AI Gateway, object storage, Drizzle) on Neon Functions',
-        description: 'A Vercel AI SDK agent on Neon Functions: streams chat through the Neon AI Gateway, generates an image with OpenAI image generation, and stores it in Neon object storage indexed in Postgres via Drizzle.',
-        services: ['Postgres', 'Functions', 'Object Storage', 'AI Gateway'],
-        source: {
-            owner: 'neondatabase',
-            repo: 'examples',
-            ref: 'main',
-            subdir: 'with-ai-sdk',
-        },
-    },
-    {
-        id: 'mastra',
-        title: 'Mastra personal agent (AI Gateway, Mastra Memory) on Neon Functions',
-        description: 'A Mastra personal-assistant agent on Neon Functions: streams chat through the Neon AI Gateway and uses Mastra Memory — backed by Neon Postgres — to remember the user across conversation threads via resource-scoped working memory.',
-        services: ['Postgres', '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 = () => ({
-    'User-Agent': 'neonctl',
-    ...(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 `services` into a clean string list. Tolerant by
- * design: a missing or non-array value yields `undefined`, and non-string items
- * are dropped, so a malformed `services` never sinks an otherwise-valid
- * template (it just renders without its badge).
- */
-const parseServices = (value) => {
-    if (!Array.isArray(value)) {
-        return undefined;
-    }
-    const services = value.filter((item) => typeof item === 'string' && item.trim() !== '');
-    return services.length > 0 ? services : 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';
-const manifestUrls = () => {
-    const override = process.env.NEON_BOOTSTRAP_MANIFEST_URL;
-    if (override) {
-        return [override];
-    }
-    return [NEON_MANIFEST_URL, GITHUB_RAW_MANIFEST_URL];
-};
-export const 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 (let i = 0; i < data.templates.length; i++) {
-        const item = data.templates[i];
-        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') {
-            log.warning('bootstrap: skipping malformed template entry at index %d in manifest.', i);
-            continue;
-        }
-        const services = parseServices(item.services);
-        templates.push({
-            id: item.id,
-            title: item.title,
-            description: item.description,
-            ...(services ? { services } : {}),
-            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
- * command never fails just because a host is down.
- */
-export const fetchTemplates = async () => {
-    for (const url of manifestUrls()) {
-        try {
-            const res = await axios.get(url, {
-                responseType: 'text',
-                headers: downloadHeaders(),
-                timeout: 10000,
-            });
-            const templates = parseManifest(res.data);
-            if (templates.length > 0) {
-                return templates;
-            }
-            log.debug('bootstrap: manifest at %s contained no templates; trying next source.', url);
-        }
-        catch (err) {
-            log.debug('bootstrap: failed to fetch manifest from %s: %s — trying next source.', url, err instanceof Error ? err.message : String(err));
-        }
-    }
-    log.debug('bootstrap: all manifest sources exhausted; using built-in defaults.');
-    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 = (err, url) => {
-    if (isAxiosError(err)) {
-        const status = err.response?.status;
-        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 err instanceof Error ? err : new Error(String(err));
-};
-/**
- * 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 axios.get(url, {
-            responseType: 'arraybuffer',
-            headers: downloadHeaders(),
-            timeout: 30000,
-        });
-        gzipped = Buffer.from(res.data);
-    }
-    catch (err) {
-        throw friendlyGithubError(err, url);
-    }
-    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}.`);
-    }
-    log.debug('bootstrap: resolved %d files for template "%s" from %s', files.length, template.id, url);
-    return files;
-};