neon 2.1.2 → 2.29.1

package/dist/utils/esbuild.js

@@ -0,0 +1,158 @@
+import { spawn } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+import which from "which";
+const NOT_FOUND = "esbuild not found. neonctl ships esbuild for most platforms; if you see " +
+    "this, install esbuild and ensure it is on your PATH (e.g. `npm i -g " +
+    "esbuild`), or set NEON_ESBUILD_PATH to an esbuild binary.";
+// Prepended to the ESM bundle. Bundled dependencies are frequently CommonJS, but an ESM
+// output (`--format=esm`) has no `require` / `__filename` / `__dirname` in scope — so any
+// bundled CJS code that calls `require(...)` would fail at load with
+// `Dynamic require of "x" is not supported`. Re-create those globals via `createRequire`
+// so CJS and ESM dependencies coexist in the single `index.mjs`.
+const ESM_CJS_INTEROP_BANNER = "import{createRequire as ___cr}from'module';import{fileURLToPath as ___f}from'url';import{dirname as ___d}from'path';const require=___cr(import.meta.url);const __filename=___f(import.meta.url);const __dirname=___d(__filename);";
+const defaultDeps = {
+    // @yao-pkg/pkg defines process.pkg inside the packaged binary.
+    isPackaged: () => process.pkg !== undefined,
+    loadEsbuild: (name) => import(name),
+};
+// Internal signal: the esbuild JS module could not be imported (exotic platform
+// or not installed). Tells bundleEntry to fall back to the binary; never shown
+// to the user.
+class ModuleNotAvailable extends Error {
+}
+const message = (err) => err instanceof Error ? err.message : String(err);
+const toFilesByBasename = (files) => {
+    const out = {};
+    for (const f of files)
+        out[basename(f.path)] = f.contents;
+    return out;
+};
+const bundleViaModule = async (source, loadEsbuild) => {
+    // esbuild is resolved by a COMPUTED specifier, never the literal string
+    // 'esbuild'. Both rollup (bundle step) and @yao-pkg/pkg (binary step)
+    // statically scan for literal import()/require() calls and would otherwise
+    // pull esbuild and its native Go binary into the bundle/snapshot — bloating
+    // the packaged CLI and emitting "cannot bundle native binary" warnings. The
+    // packaged binary never imports esbuild at all (the isPackaged guard sends it
+    // to the binary path), so keeping this specifier invisible to the scanners is
+    // what keeps esbuild out of the snapshot.
+    // Do NOT "simplify" this back to import('esbuild').
+    const name = ["es", "build"].join("");
+    let esbuild;
+    try {
+        esbuild = await loadEsbuild(name);
+    }
+    catch {
+        throw new ModuleNotAvailable();
+    }
+    // Mirrors the binary-path bundling flags; write:false keeps output in memory.
+    // logLevel:'silent' suppresses esbuild's own stderr — the rejected error
+    // still carries the diagnostic, matching the binary path's captured-stderr.
+    const result = await esbuild
+        .build({
+        entryPoints: [source],
+        bundle: true,
+        // Emit `index.mjs` (not `out.js`): the Functions runtime imports the archive's entry
+        // by the conventional `index.{js,mjs}` name, and `.mjs` makes Node treat the ESM
+        // output as a module without needing a `package.json` type marker alongside it.
+        outfile: "index.mjs",
+        write: false,
+        minify: true,
+        format: "esm",
+        platform: "node",
+        // Bundle dependencies into the entry so the deployed archive is self-contained (the
+        // Functions runtime has no node_modules). Node built-ins stay external on
+        // platform:'node'. The banner re-creates require/__filename/__dirname for bundled CJS.
+        banner: { js: ESM_CJS_INTEROP_BANNER },
+        logLevel: "silent",
+    })
+        .catch((err) => {
+        throw new Error(`Failed to bundle function from ${source}. ${message(err)}`.trim());
+    });
+    const files = result.outputFiles ?? [];
+    // write:false with one entry always yields index.mjs (no source map — we don't emit one);
+    // an empty set means the API contract changed under us — fail loud rather than ship an
+    // empty archive.
+    if (files.length === 0) {
+        throw new Error(`Failed to bundle function from ${source}. esbuild produced no output.`);
+    }
+    return toFilesByBasename(files);
+};
+// Find the esbuild binary at deploy time. An explicit override is authoritative
+// (so it fails loudly if wrong); otherwise prefer the host PATH, then a locally
+// installed copy.
+const resolveEsbuild = () => {
+    const override = process.env.NEON_ESBUILD_PATH;
+    if (override) {
+        if (existsSync(override))
+            return override;
+        throw new Error(NOT_FOUND);
+    }
+    const onPath = which.sync("esbuild", { nothrow: true });
+    if (onPath)
+        return onPath;
+    // CWD-relative (not install-relative): helps the dev checkout where esbuild is
+    // a devDependency. In `npm i -g` and pkg installs the PATH branch above wins.
+    const local = join(process.cwd(), "node_modules", ".bin", "esbuild");
+    if (existsSync(local))
+        return local;
+    throw new Error(NOT_FOUND);
+};
+const runEsbuild = (bin, args) => new Promise((resolve, reject) => {
+    // stderr is captured (NOT inherited): with --log-level=error a success emits
+    // nothing, and a failure's diagnostic is read out below. Never use 'inherit'.
+    const child = spawn(bin, args, { stdio: ["ignore", "ignore", "pipe"] });
+    let stderr = "";
+    child.stderr.on("data", (chunk) => {
+        stderr += chunk.toString();
+    });
+    child.on("error", reject);
+    child.on("close", (code) => {
+        resolve({ code, stderr });
+    });
+});
+const bundleViaBinary = async (source) => {
+    const bin = resolveEsbuild();
+    const outDir = mkdtempSync(join(tmpdir(), "neon-fn-bundle-"));
+    const outfile = join(outDir, "index.mjs");
+    try {
+        const { code, stderr } = await runEsbuild(bin, [
+            source,
+            "--bundle",
+            `--outfile=${outfile}`,
+            "--minify",
+            "--format=esm",
+            "--platform=node",
+            `--banner:js=${ESM_CJS_INTEROP_BANNER}`,
+            "--log-level=error",
+        ]);
+        if (code !== 0) {
+            throw new Error(`Failed to bundle function from ${source}. ${stderr.trim()}`.trim());
+        }
+        // No `--sourcemap`: the Functions runtime has no source-map support, so an uploaded
+        // `index.mjs.map` is never consumed — emitting it only inflated the archive.
+        return {
+            "index.mjs": new Uint8Array(readFileSync(outfile)),
+        };
+    }
+    finally {
+        rmSync(outDir, { recursive: true, force: true });
+    }
+};
+// Bundle `source` into the files the Functions archive expects, keyed by
+// basename. npm installs bundle in-process via the esbuild module; the packaged
+// binary (and platforms esbuild can't run on) shell out to an esbuild binary.
+export const bundleEntry = async (source, deps = defaultDeps) => {
+    if (deps.isPackaged())
+        return bundleViaBinary(source);
+    try {
+        return await bundleViaModule(source, deps.loadEsbuild);
+    }
+    catch (err) {
+        if (err instanceof ModuleNotAvailable)
+            return bundleViaBinary(source);
+        throw err;
+    }
+};

package/dist/utils/formats.js

@@ -0,0 +1,18 @@
+const HAIKU_REGEX = /^[a-z0-9]+-[a-z0-9]+-[a-z0-9]+$/;
+export const looksLikeBranchId = (branch) => branch.startsWith("br-") && HAIKU_REGEX.test(branch.substring(3));
+const LSN_REGEX = /^[a-fA-F0-9]{1,8}\/[a-fA-F0-9]{1,8}$/;
+export const looksLikeLSN = (lsn) => LSN_REGEX.test(lsn);
+export const looksLikeTimestamp = (timestamp) => {
+    if (isNaN(Date.parse(timestamp)))
+        return false;
+    /**
+     * @info
+     * Check for ISO 8601/RFC 3339 format patterns
+     * Must contain 'T' separator and end with 'Z' or timezone offset
+     *
+     * `Date.parse` aggressive parsing will attempt a date out of any string.
+     * so if a branch name has a number, `Date.parse` will return a valid timestamp.
+     */
+    const iso8601Regex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?([+-]\d{2}:\d{2}|Z)$/;
+    return iso8601Regex.test(timestamp);
+};

package/dist/utils/middlewares.js

@@ -0,0 +1,20 @@
+/**
+ * This middleware is needed to fill in the args for nested objects,
+ * so that required arguments would work
+ * otherwise yargs just throws an error
+ */
+export const fillInArgs = (args, currentArgs = args, acc = []) => {
+    Object.entries(currentArgs).forEach(([k, v]) => {
+        if (k === "_" || k === "--") {
+            return;
+        }
+        // check if the value is an Object
+        if (typeof v === "object" && v !== null) {
+            fillInArgs(args, v, [...acc, k]);
+        }
+        else if (acc.length > 0) {
+            // if it's not an object, and we have a path, fill it in
+            args[acc.join(".") + "." + k] = v;
+        }
+    });
+};

package/dist/utils/package_manager.js

@@ -0,0 +1,68 @@
+import { spawn } from "node:child_process";
+import which from "which";
+import { log } from "../log.js";
+// npm first so it's the default/preselected choice; the rest follow in rough
+// popularity order.
+export 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 …` installs with pnpm). Returns
+ * undefined when there's nothing to infer from — e.g. a globally-installed
+ * `neon`/`neonctl` — so the caller can ask (or fall back) instead of silently
+ * assuming npm.
+ */
+export 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. */
+export const installedPackageManagers = () => PACKAGE_MANAGERS.filter((pm) => which.sync(pm, { nothrow: true }) !== null);
+/**
+ * Pick a package manager without prompting: the one the CLI was invoked through,
+ * else the first one installed, else npm. Used by non-interactive flows (e.g.
+ * `config init`) where there's no scaffold prompt to hang a picker off.
+ */
+export const resolvePackageManager = () => detectPackageManager() ?? installedPackageManagers()[0] ?? "npm";
+/**
+ * The argv that adds `packages` as runtime dependencies with `pm`. npm spells it
+ * `install`; pnpm/yarn/bun use `add`.
+ */
+export const addDependenciesArgs = (pm, packages) => (pm === "npm" ? ["install", ...packages] : ["add", ...packages]);
+/**
+ * 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 throws — the caller
+ * decides whether to treat it as fatal.
+ */
+export 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);
+    });
+});

package/dist/utils/point_in_time.js

@@ -0,0 +1,56 @@
+import { branchIdResolve } from "./enrichers.js";
+import { looksLikeLSN, looksLikeTimestamp } from "./formats.js";
+export class PointInTimeParseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PointInTimeParseError";
+    }
+}
+export const parsePITBranch = (input) => {
+    const splitIndex = input.lastIndexOf("@");
+    const sourceBranch = splitIndex === -1 ? input : input.slice(0, splitIndex);
+    const exactPIT = splitIndex === -1 ? null : input.slice(splitIndex + 1);
+    const result = {
+        branch: sourceBranch,
+        ...(exactPIT === null
+            ? { tag: "head" }
+            : looksLikeLSN(exactPIT)
+                ? { tag: "lsn", lsn: exactPIT }
+                : { tag: "timestamp", timestamp: exactPIT }),
+    };
+    if (result.tag === "timestamp") {
+        const timestamp = result.timestamp;
+        if (!looksLikeTimestamp(timestamp)) {
+            throw new PointInTimeParseError(`Invalid source branch format - ${input}`);
+        }
+        if (Date.parse(timestamp) > Date.now()) {
+            throw new PointInTimeParseError(`Timestamp can not be in future - ${input}`);
+        }
+    }
+    return result;
+};
+export const parsePointInTime = async ({ pointInTime, targetBranchId, projectId, api, }) => {
+    const parsedPIT = parsePITBranch(pointInTime);
+    let branchId = "";
+    if (parsedPIT.branch === "^self") {
+        branchId = targetBranchId;
+    }
+    else if (parsedPIT.branch === "^parent") {
+        const { data } = await api.getProjectBranch(projectId, targetBranchId);
+        const { parent_id: parentId } = data.branch;
+        if (parentId == null) {
+            throw new PointInTimeParseError("Branch has no parent");
+        }
+        branchId = parentId;
+    }
+    else {
+        branchId = await branchIdResolve({
+            branch: parsedPIT.branch,
+            projectId,
+            apiClient: api,
+        });
+    }
+    // @ts-expect-error extracting pit from parsedPIT
+    delete parsedPIT.branch;
+    return { ...parsedPIT, branchId };
+};

package/dist/utils/psql.js

@@ -0,0 +1,120 @@
+import { spawn } from "child_process";
+import which from "which";
+import { closeAnalytics, trackEvent } from "../analytics.js";
+import { log } from "../log.js";
+const FALLBACK_ENV = "NEONCTL_PSQL_FALLBACK";
+/** Max time we wait for the analytics flush before handing off to psql. */
+const ANALYTICS_FLUSH_TIMEOUT_MS = 3000;
+/**
+ * Decide which psql implementation will run, and why. The PATH probe is
+ * skipped when TS is forced (flag or env) — we don't need it and it'd be a
+ * wasted lookup — so `nativeAvailable` is `null` ("not checked") in those
+ * cases rather than a misleading `false`.
+ */
+const planPsql = async (opts) => {
+    if (opts.mode === "ts") {
+        return {
+            implementation: "ts",
+            reason: "forced_flag",
+            nativeAvailable: null,
+            nativePath: null,
+        };
+    }
+    if (process.env[FALLBACK_ENV] === "1") {
+        return {
+            implementation: "ts",
+            reason: "forced_env",
+            nativeAvailable: null,
+            nativePath: null,
+        };
+    }
+    const nativePath = await which("psql", { nothrow: true });
+    const nativeAvailable = nativePath !== null;
+    if (opts.mode === "native") {
+        return {
+            implementation: "native",
+            reason: "forced_native",
+            nativeAvailable,
+            nativePath,
+        };
+    }
+    // 'auto' (or unset): strict fallback — prefer native, TS only if missing.
+    return nativeAvailable
+        ? {
+            implementation: "native",
+            reason: "native_available",
+            nativeAvailable,
+            nativePath,
+        }
+        : {
+            implementation: "ts",
+            reason: "fallback_no_native",
+            nativeAvailable,
+            nativePath,
+        };
+};
+/**
+ * Record which psql implementation is about to run, then flush analytics.
+ *
+ * Both exec paths below call `process.exit()`, which short-circuits the
+ * main loop's `closeAnalytics()` — so without flushing here the event (and
+ * any earlier queued events, e.g. `CLI Started`) would be dropped. The
+ * flush is bounded by {@link ANALYTICS_FLUSH_TIMEOUT_MS} so a slow or
+ * unreachable analytics endpoint can't stall the psql launch. No-ops when
+ * analytics is disabled (`--analytics false`), since the client is absent.
+ */
+const reportPsqlInvocation = async (plan) => {
+    trackEvent("psql_invoked", {
+        implementation: plan.implementation,
+        reason: plan.reason,
+        nativeAvailable: plan.nativeAvailable,
+    });
+    await closeAnalytics({ timeout: ANALYTICS_FLUSH_TIMEOUT_MS });
+};
+const execNative = async (binary, connection_uri, args) => {
+    log.info("Connecting to the database using psql...");
+    const child = spawn(binary, [connection_uri, ...args], {
+        stdio: "inherit",
+    });
+    for (const signame of ["SIGINT", "SIGTERM"]) {
+        process.on(signame, (code) => {
+            if (!child.killed && code !== null) {
+                child.kill(code);
+            }
+        });
+    }
+    return new Promise((_, reject) => {
+        child.on("exit", (code) => {
+            process.exit(code === null ? 1 : code);
+        });
+        child.on("error", reject);
+    });
+};
+const execTs = async (connection_uri, args) => {
+    log.info("Connecting to the database using embedded psql (TypeScript)...");
+    const { runPsql } = await import("../psql/index.js");
+    const code = await runPsql([connection_uri, ...args], {
+        stdin: process.stdin,
+        stdout: process.stdout,
+        stderr: process.stderr,
+    });
+    process.exit(code);
+};
+export const psql = async (connection_uri, args = [], opts = {}) => {
+    const plan = await planPsql(opts);
+    await reportPsqlInvocation(plan);
+    if (plan.implementation === "ts") {
+        if (plan.reason === "fallback_no_native") {
+            log.info("psql binary not found on PATH; falling back to embedded TypeScript psql");
+        }
+        return execTs(connection_uri, args);
+    }
+    // implementation === 'native'
+    if (plan.nativePath === null) {
+        // Only reachable when native was explicitly requested (mode: 'native')
+        // but no binary is on PATH.
+        log.error(`psql is not available in the PATH`);
+        process.exit(1);
+    }
+    return execNative(plan.nativePath, connection_uri, args);
+};

package/dist/utils/string.js

@@ -0,0 +1,5 @@
+export const toSnakeCase = (str) => str
+    .split(" ")
+    .map((word) => word.toLowerCase())
+    .join("_");
+export const isObject = (value) => value != null && value === Object(value);

package/dist/utils/ui.js

@@ -0,0 +1,59 @@
+// returns the next string if matches the given matcher,
+// otherwise returns null
+// consumes the line from the lines array
+export const consumeNextMatching = (lines, matcher) => {
+    while (lines.length > 0) {
+        const line = lines.shift().trim();
+        if (line === "") {
+            continue;
+        }
+        if (matcher.test(line)) {
+            return line;
+        }
+        return null;
+    }
+    return null;
+};
+// returns strings if next non-empty line matches the given matcher,
+// otherwise returns empty array
+// consumes the lines from the lines array
+export const consumeBlockIfMatches = (lines, matcher) => {
+    const result = [];
+    if (lines.length === 0) {
+        return result;
+    }
+    let line = lines.shift();
+    while (line.trim() === "") {
+        line = lines.shift();
+    }
+    if (!matcher.test(line)) {
+        lines.unshift(line);
+        return result;
+    }
+    result.push(line);
+    while (lines.length > 0) {
+        line = lines.shift();
+        if (line.trim() === "") {
+            break;
+        }
+        result.push(line);
+    }
+    return result;
+};
+export const splitColumns = (line) => {
+    const result = line.trim().split(/\s{2,}/);
+    result[1] = result[1] ?? "";
+    if (result.length > 2) {
+        result[1] = result.slice(1).join(" ");
+    }
+    return result;
+};
+export const drawPointer = (width) => {
+    const result = [];
+    result.push("└");
+    for (let i = 0; i < width - 4; i++) {
+        result.push("─");
+    }
+    result.push(">");
+    return result.join("");
+};

package/dist/utils/zip.js

@@ -0,0 +1,4 @@
+import { zipSync } from "fflate";
+// Zip the esbuild output (index.mjs) into the archive the Functions deploy endpoint
+// expects. Compression level 6 matches the previous bundler.
+export const zipBundle = (entries) => zipSync(entries, { level: 6 });

package/dist/writer.js

@@ -0,0 +1,97 @@
+import chalk from "chalk";
+import Table from "cli-table";
+import YAML from "yaml";
+import { isCi } from "./env.js";
+import { isObject, toSnakeCase } from "./utils/string.js";
+const writeYaml = (chunks) => {
+    return YAML.stringify(chunks.length === 1
+        ? chunks[0].data
+        : Object.fromEntries(chunks.map(({ config, data }, idx) => [
+            config.title ? toSnakeCase(config.title) : idx,
+            data,
+        ])), null, 2);
+};
+const writeJson = (chunks) => {
+    return JSON.stringify(chunks.length === 1
+        ? chunks[0].data
+        : Object.fromEntries(chunks.map(({ config, data }, idx) => [
+            config.title ? toSnakeCase(config.title) : idx,
+            data,
+        ])), null, 2);
+};
+const writeTable = (chunks, out) => {
+    chunks.forEach(({ data, config: { emptyMessage, fields, title, renderColumns = {} }, }) => {
+        const arrayData = Array.isArray(data) ? data : [data];
+        if (!arrayData.length && emptyMessage) {
+            out.write("\n" + emptyMessage + "\n");
+            return;
+        }
+        const fieldsFiltered = fields.filter((field) => arrayData.some((item) => item[field] !== undefined && item[field] !== ""));
+        const table = new Table({
+            style: {
+                head: ["green"],
+            },
+            head: fieldsFiltered.map((field) => field
+                .split("_")
+                .map((word) => word[0].toUpperCase() + word.slice(1))
+                .join(" ")),
+        });
+        arrayData.forEach((item) => {
+            table.push(fieldsFiltered.map((field) => {
+                const value = item[field];
+                if (renderColumns[field]) {
+                    return renderColumns[field]?.(item);
+                }
+                return Array.isArray(value)
+                    ? value.join("\n")
+                    : isObject(value)
+                        ? JSON.stringify(value, null, 2)
+                        : (value ?? "");
+            }));
+        });
+        if (title) {
+            out.write((isCi() ? title : chalk.bold(title)) + "\n");
+        }
+        out.write(table.toString());
+        out.write("\n");
+    });
+};
+/**
+ *
+ * Parses the output format, takes data and writes the output to stdout.
+ *
+ * @example
+ * const { data } = await props.apiClient.listProjectBranches(props.project.id);
+ * // to output single data
+ * writer(props).end(data, { fields: ['id', 'name', 'created_at'] })
+ * // to output multiple data
+ * writer(props)
+ *   .write(data, { fields: ['id', 'name', 'created_at'], title: 'branches' })
+ *   .write(data, { fields: ['id', 'created_at'], title: 'endpoints' })
+ *   .end()
+ */
+export const writer = (props) => {
+    const out = props.out ?? process.stdout;
+    const chunks = [];
+    return {
+        write(data, config) {
+            chunks.push({ data, config });
+            return this;
+        },
+        text(data) {
+            return out.write(data);
+        },
+        end: (...args) => {
+            if (args.length === 2) {
+                chunks.push({ data: args[0], config: args[1] });
+            }
+            if (props.output == "yaml") {
+                return out.write(writeYaml(chunks));
+            }
+            if (props.output == "json") {
+                return out.write(writeJson(chunks));
+            }
+            writeTable(chunks, out);
+        },
+    };
+};