neonctl 2.23.0 → 2.24.0

package/dev/runtime.js

@@ -0,0 +1,146 @@
+import { createServer } from 'node:http';
+import { pathToFileURL } from 'node:url';
+import { resolve } from 'node:path';
+import { getRequestListener } from '@hono/node-server';
+const isFunction = (value) => typeof value === 'function';
+const hasFetchMethod = (value) => typeof value === 'object' &&
+    value !== null &&
+    'fetch' in value &&
+    typeof value.fetch === 'function';
+/**
+ * Resolve the user's exported handler to a single fetch callback.
+ *
+ * Resolution order (first match wins):
+ *   1. `export default { fetch }`      — Workers / Neon Functions style
+ *   2. `export default function (req)` — bare (async) default function
+ */
+export const resolveFetchHandler = (mod) => {
+    const defaultExport = mod.default;
+    if (hasFetchMethod(defaultExport)) {
+        const target = defaultExport;
+        return (req) => target.fetch(req);
+    }
+    if (isFunction(defaultExport)) {
+        return defaultExport;
+    }
+    throw new Error('No request handler found in the source module. Export one of:\n' +
+        '  export default { fetch(req) { /* ... */ } }\n' +
+        '  export default function (req) { /* ... */ }');
+};
+/**
+ * Wrap a fetch handler so user errors become a 500 response (with the message
+ * in the body during dev) instead of crashing the child process.
+ */
+export const withErrorBoundary = (handler) => {
+    return async (req) => {
+        try {
+            return await handler(req);
+        }
+        catch (err) {
+            const message = err instanceof Error ? (err.stack ?? err.message) : String(err);
+            process.stderr.write(`Request handler threw an error:\n${message}\n`);
+            return new Response(`Internal Server Error\n\n${message}`, {
+                status: 500,
+                headers: { 'content-type': 'text/plain; charset=utf-8' },
+            });
+        }
+    };
+};
+const isAddressInUse = (err) => typeof err === 'object' &&
+    err !== null &&
+    err.code === 'EADDRINUSE';
+const DEFAULT_SEARCH_BASE = 8787;
+const MAX_SEARCH_STEPS = 100;
+const bindPort = async (server, selection, hostname) => {
+    if (selection.mode === 'explicit') {
+        return listen(server, selection.port, hostname);
+    }
+    for (let step = 0; step < MAX_SEARCH_STEPS; step++) {
+        try {
+            return await listen(server, selection.from + step, hostname);
+        }
+        catch (err) {
+            if (!isAddressInUse(err))
+                throw err;
+        }
+    }
+    throw new Error(`Could not find a free port in ${selection.from}-${selection.from + MAX_SEARCH_STEPS - 1}`);
+};
+const listen = (server, port, hostname) => new Promise((resolveListen, rejectListen) => {
+    const onError = (err) => {
+        server.off('listening', onListening);
+        rejectListen(err);
+    };
+    const onListening = () => {
+        server.off('error', onError);
+        resolveListen(server.address().port);
+    };
+    server.once('error', onError);
+    server.once('listening', onListening);
+    server.listen(port, hostname);
+});
+/**
+ * Load the (already-bundled) user module, build the listener, and start an HTTP
+ * server. Announces the bound port on stdout as `neon-dev:ready <port>` so the
+ * parent can render the URL. Resolves with the bound port.
+ */
+export const startRuntime = async ({ source, port, hostname, }) => {
+    const absoluteSource = resolve(process.cwd(), source);
+    const mod = (await import(pathToFileURL(absoluteSource).href));
+    const handler = withErrorBoundary(resolveFetchHandler(mod));
+    const listener = getRequestListener(handler, { hostname });
+    const server = createServer((incoming, outgoing) => {
+        void listener(incoming, outgoing);
+    });
+    const boundPort = await bindPort(server, port, hostname);
+    process.stdout.write(`neon-dev:ready ${boundPort}\n`);
+    return boundPort;
+};
+/**
+ * Build a {@link PortSelection} from the environment. Precedence:
+ *   1. `NEON_DEV_PORT` -> explicit bind (crash if taken). Set by `neon dev` from an
+ *      explicit `--port` / `dev.port`.
+ *   2. `PORT`          -> explicit bind. This is what `portless` injects (and what a bare
+ *      `PORT=3000 neon dev` sets), so the runtime binds the port chosen for it.
+ *   3. otherwise        -> search upward from `NEON_DEV_PORT_BASE` (or the default base).
+ */
+export const portSelectionFromEnv = (env) => {
+    const explicit = env.NEON_DEV_PORT;
+    if (explicit !== undefined && explicit !== '') {
+        return { mode: 'explicit', port: parsePort(explicit, 'NEON_DEV_PORT') };
+    }
+    const injected = env.PORT;
+    if (injected !== undefined && injected !== '') {
+        return { mode: 'explicit', port: parsePort(injected, 'PORT') };
+    }
+    const base = Number(env.NEON_DEV_PORT_BASE ?? DEFAULT_SEARCH_BASE);
+    return {
+        mode: 'search',
+        from: Number.isInteger(base) ? base : DEFAULT_SEARCH_BASE,
+    };
+};
+const parsePort = (value, varName) => {
+    const port = Number(value);
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        throw new Error(`Invalid ${varName}: "${value}"`);
+    }
+    return port;
+};
+const isDirectExecution = () => {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    return import.meta.url === pathToFileURL(entry).href;
+};
+if (isDirectExecution()) {
+    const source = process.env.NEON_DEV_SOURCE ?? process.argv[2];
+    if (!source) {
+        process.stderr.write('neon-dev runtime: missing source path\n');
+        process.exit(1);
+    }
+    startRuntime({ source, port: portSelectionFromEnv(process.env) }).catch((err) => {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`neon-dev runtime failed to start: ${msg}\n`);
+        process.exit(1);
+    });
+}

package/env_file.js

@@ -0,0 +1,146 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Default dotenv file `env pull` writes to: `.env` when one already exists in the working
+ * directory (update where secrets already live), otherwise `.env.local` — matching the
+ * `vercel env pull` convention. An explicit `--file` always wins over this.
+ */
+export const resolveEnvFilePath = (cwd, file) => {
+    if (file)
+        return join(cwd, file);
+    if (existsSync(join(cwd, '.env')))
+        return join(cwd, '.env');
+    return join(cwd, '.env.local');
+};
+/**
+ * Merge `updates` into the dotenv content at `path`, preserving every other line
+ * (comments, blank lines, unrelated keys) and the file's existing order. Keys present in
+ * both are updated in place; keys only in `updates` are appended. A non-existent file is
+ * treated as empty. Returns the list of keys that were written (for reporting).
+ */
+export const mergeEnvFile = (path, updates) => {
+    const original = existsSync(path) ? readFileSync(path, 'utf8') : '';
+    const { content, written } = mergeEnvContent(original, updates);
+    writeFileSync(path, content);
+    return { written };
+};
+/**
+ * Pure core of {@link mergeEnvFile}: takes the current file content and the updates, and
+ * returns the new content plus which keys were written. Kept side-effect-free so it can be
+ * unit-tested without touching the filesystem.
+ */
+export const mergeEnvContent = (original, updates) => {
+    const keys = Object.keys(updates);
+    if (keys.length === 0)
+        return { content: original, written: [] };
+    const remaining = new Set(keys);
+    const lines = original === '' ? [] : original.split('\n');
+    // Update keys in place where they already appear, so their position and any surrounding
+    // comments are preserved.
+    const updatedLines = lines.map((line) => {
+        const key = parseKey(line);
+        if (key !== null && remaining.has(key)) {
+            remaining.delete(key);
+            return formatLine(key, updates[key]);
+        }
+        return line;
+    });
+    // Append keys that weren't already present, in the order they were given.
+    const appended = keys
+        .filter((key) => remaining.has(key))
+        .map((key) => formatLine(key, updates[key]));
+    const body = trimTrailingBlank(updatedLines);
+    const content = [...body, ...appended].join('\n');
+    return {
+        // A dotenv file ends with a trailing newline.
+        content: content === '' ? '' : `${content}\n`,
+        written: keys,
+    };
+};
+/**
+ * Read a dotenv file at `path` into a plain `{ KEY: value }` map. A non-existent file is an
+ * error (callers pass an explicit `--env` path, so a typo should fail loudly rather than
+ * silently load nothing). Quotes are stripped and `\"` / `\\` unescaped, matching the
+ * quoting {@link mergeEnvFile} writes. Comments, blank lines, and non-assignment lines are
+ * ignored.
+ */
+export const readEnvFile = (path) => {
+    if (!existsSync(path)) {
+        throw new Error(`Env file not found: ${path}`);
+    }
+    const out = {};
+    for (const line of readFileSync(path, 'utf8').split('\n')) {
+        const parsed = parseAssignment(line);
+        if (parsed)
+            out[parsed.key] = parsed.value;
+    }
+    return out;
+};
+/**
+ * Load a dotenv file into `process.env` so values are available to anything read later
+ * (e.g. a `neon.ts` whose function `env` values come from `process.env.X`). Existing
+ * `process.env` entries are **not** overridden — an already-exported var wins over the
+ * file, matching dotenv's default. Returns the keys that were applied.
+ */
+export const loadEnvFileIntoProcess = (path) => {
+    const parsed = readEnvFile(path);
+    const applied = [];
+    for (const [key, value] of Object.entries(parsed)) {
+        if (process.env[key] === undefined) {
+            process.env[key] = value;
+            applied.push(key);
+        }
+    }
+    return applied;
+};
+/**
+ * Extract the variable name from a dotenv line, or `null` for comments / blank lines / any
+ * line that isn't a `KEY=value` assignment. Tolerates a leading `export ` and surrounding
+ * whitespace, matching common `.env` styles.
+ */
+const parseKey = (line) => {
+    const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line);
+    return match ? match[1] : null;
+};
+/**
+ * Parse a `KEY=value` dotenv line into its key and unquoted value, or `null` for
+ * comments / blank lines / non-assignments. Mirrors {@link formatLine}'s quoting.
+ */
+const parseAssignment = (line) => {
+    const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+    const key = match?.[1];
+    const raw = match?.[2];
+    if (key === undefined || raw === undefined)
+        return null;
+    return { key, value: unquote(raw.trim()) };
+};
+/** Strip matching surrounding quotes and unescape `\"` / `\\` inside double quotes. */
+const unquote = (value) => {
+    if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+        return value.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+    }
+    if (value.length >= 2 && value.startsWith("'") && value.endsWith("'")) {
+        return value.slice(1, -1);
+    }
+    return value;
+};
+/**
+ * Render a `KEY=value` line. The value is wrapped in double quotes when it contains
+ * characters that would otherwise break parsing (spaces, `#`, quotes, `=`), with inner
+ * quotes/backslashes escaped — Neon connection strings and URLs are safe either way, but
+ * quoting defensively avoids surprises for tools that re-parse the file.
+ */
+const formatLine = (key, value) => {
+    const needsQuotes = /[\s#"'=]/.test(value);
+    if (!needsQuotes)
+        return `${key}=${value}`;
+    const escaped = value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    return `${key}="${escaped}"`;
+};
+/** Drop trailing blank lines so we don't accumulate them across repeated merges. */
+const trimTrailingBlank = (lines) => {
+    const out = [...lines];
+    while (out.length > 0 && out[out.length - 1]?.trim() === '')
+        out.pop();
+    return out;
+};

package/functions_api.js

@@ -28,7 +28,6 @@ export const deleteFunction = async (apiClient, projectId, branchId, slug) => {
 export const createDeployment = async (apiClient, projectId, branchId, slug, params) => {
     const form = new FormData();
     form.append('zip', new Blob([params.zip]), 'bundle.zip');
-    form.append('memory_mib', String(params.memoryMib));
     form.append('runtime', params.runtime);
     if (params.environment)
         form.append('environment', params.environment);

package/index.js

@@ -38,6 +38,8 @@ const NO_SUBCOMMANDS_VERBS = [
     'checkout',
     'link',
     'init',
+    'dev',
+    'deploy',
     // aliases
 ];
 let builder = yargs(hideBin(process.argv));

package/package.json

@@ -5,7 +5,7 @@
     "url": "git+ssh://git@github.com/neondatabase/neonctl.git"
   },
   "type": "module",
-  "version": "2.23.0",
+  "version": "2.24.0",
   "description": "CLI tool for NeonDB Cloud management",
   "main": "index.js",
   "author": "NeonDB",
@@ -49,7 +49,7 @@
     "rollup": "3.29.4",
     "strip-ansi": "7.1.0",
     "tsx": "4.22.3",
-    "typescript": "4.9.5",
+    "typescript": "5.8.3",
     "typescript-eslint": "8.28.0",
     "vitest": "1.6.1"
   },
@@ -57,11 +57,16 @@
     "esbuild": "0.28.0"
   },
   "dependencies": {
+    "@hono/node-server": "2.0.4",
     "@neondatabase/api-client": "2.7.1",
+    "@neondatabase/config": "0.4.0",
+    "@neondatabase/config-runtime": "0.4.0",
+    "@neondatabase/env": "0.3.0",
     "@segment/analytics-node": "1.3.0",
     "axios": "1.7.2",
     "axios-debug-log": "1.0.0",
     "chalk": "5.3.0",
+    "chokidar": "5.0.0",
     "cli-table": "0.3.11",
     "cliui": "8.0.1",
     "diff": "5.2.0",

package/psql/command/cmd_format.js

@@ -233,18 +233,18 @@ const NORMALISED_ENCODINGS = new Set([
     'johab',
     'shiftjis2004',
     // Aliases upstream's encoding_match_list accepts as recognised names.
-    'unicode',
-    'mskanji',
-    'shiftjis',
-    'windows949',
-    'windows950',
-    'windows936',
-    'tcvn',
-    'tcvn5712',
-    'vscii',
-    'alt',
-    'win',
-    'koi8',
+    'unicode', // → UTF8
+    'mskanji', // → SJIS
+    'shiftjis', // → SJIS
+    'windows949', // → UHC
+    'windows950', // → BIG5
+    'windows936', // → GBK
+    'tcvn', // → WIN1258
+    'tcvn5712', // → WIN1258
+    'vscii', // → WIN1258
+    'alt', // → WIN866
+    'win', // → WIN1251
+    'koi8', // → KOI8R
     'abc', // → WIN1258
 ]);
 /**

package/psql/command/cmd_io.js

@@ -1514,7 +1514,7 @@ const GDESC_SYNTHETIC_FIELDS = [
         name: 'Column',
         tableID: 0,
         columnID: 0,
-        dataTypeID: 25,
+        dataTypeID: 25, // text
         dataTypeSize: -1,
         dataTypeModifier: -1,
         format: 0,
@@ -1523,7 +1523,7 @@ const GDESC_SYNTHETIC_FIELDS = [
         name: 'Type',
         tableID: 0,
         columnID: 0,
-        dataTypeID: 25,
+        dataTypeID: 25, // text
         dataTypeSize: -1,
         dataTypeModifier: -1,
         format: 0,

package/psql/command/cmd_restrict.js

@@ -48,18 +48,18 @@ export const RESTRICTED_REFUSAL_MESSAGE = (cmdName) => `\\${cmdName}: command is
  * registry level" and avoids touching cmd_copy.ts internals.
  */
 export const RESTRICTED_COMMANDS = new Set([
-    '!',
-    'cd',
-    'copy',
-    'setenv',
-    'w',
+    '!', // shell escape
+    'cd', // change directory
+    'copy', // \copy — including \copy FROM PROGRAM
+    'setenv', // mutate process env
+    'w', // \w / \write — file write of query buffer
     // `\o`/`\g`/`\gx` route through openWriter(), which spawns `sh -c <cmd>`
     // for a `|command` target (arbitrary shell exec) and writes the filesystem
     // for a FILE target; `\s FILE` writes history to disk. Block them by name
     // (review item #13). Plain query execution still works via `;`.
-    'o',
-    'g',
-    'gx',
+    'o', // \o [FILE | |cmd]
+    'g', // \g [FILE | |cmd]
+    'gx', // \gx [FILE | |cmd]
     's', // \s [FILE] — write command history
 ]);
 /**

package/psql/describe/formatters.js

@@ -1270,7 +1270,7 @@ const fakeField = (name) => ({
     name,
     tableID: 0,
     columnID: 0,
-    dataTypeID: 25,
+    dataTypeID: 25, // text
     dataTypeSize: -1,
     dataTypeModifier: -1,
     format: 0,

package/psql/print/aligned.js

@@ -16,28 +16,28 @@ import { formatNumericLocale } from './units.js';
 // East-Asian wide / fullwidth ranges from Unicode Standard Annex #11.
 // Trimmed to the ranges psql's `ucs_wcwidth` considers width 2.
 const WIDE_RANGES = [
-    [0x1100, 0x115f],
-    [0x2329, 0x232a],
-    [0x2e80, 0x303e],
-    [0x3041, 0x33ff],
-    [0x3400, 0x4dbf],
-    [0x4e00, 0x9fff],
-    [0xa000, 0xa4cf],
-    [0xac00, 0xd7a3],
-    [0xf900, 0xfaff],
-    [0xfe10, 0xfe19],
-    [0xfe30, 0xfe6f],
-    [0xff00, 0xff60],
-    [0xffe0, 0xffe6],
-    [0x1f300, 0x1f64f],
-    [0x1f900, 0x1f9ff],
-    [0x20000, 0x2fffd],
+    [0x1100, 0x115f], // Hangul Jamo
+    [0x2329, 0x232a], // Angle brackets
+    [0x2e80, 0x303e], // CJK Radicals, Kangxi, ...
+    [0x3041, 0x33ff], // Hiragana, Katakana, Bopomofo, etc.
+    [0x3400, 0x4dbf], // CJK Unified Ideographs Extension A
+    [0x4e00, 0x9fff], // CJK Unified Ideographs
+    [0xa000, 0xa4cf], // Yi Syllables
+    [0xac00, 0xd7a3], // Hangul Syllables
+    [0xf900, 0xfaff], // CJK Compatibility Ideographs
+    [0xfe10, 0xfe19], // Vertical forms
+    [0xfe30, 0xfe6f], // CJK Compatibility Forms, Small Form Variants
+    [0xff00, 0xff60], // Fullwidth Forms
+    [0xffe0, 0xffe6], // Fullwidth signs
+    [0x1f300, 0x1f64f], // Misc Symbols & Pictographs, Emoticons
+    [0x1f900, 0x1f9ff], // Supplemental Symbols & Pictographs
+    [0x20000, 0x2fffd], // CJK Extension B..F
     [0x30000, 0x3fffd], // CJK Extension G
 ];
 // Combining marks: width 0. From Unicode general categories Mn/Me/Cf
 // and the zero-width controls upstream treats as width 0.
 const ZERO_RANGES = [
-    [0x0300, 0x036f],
+    [0x0300, 0x036f], // Combining Diacritical Marks
     [0x0483, 0x0489],
     [0x0591, 0x05bd],
     [0x05bf, 0x05bf],
@@ -190,7 +190,7 @@ const ZERO_RANGES = [
     [0x1cf8, 0x1cf9],
     [0x1dc0, 0x1df9],
     [0x1dfb, 0x1dff],
-    [0x200b, 0x200f],
+    [0x200b, 0x200f], // zero-width space, ZWNJ, ZWJ, LRM, RLM
     [0x202a, 0x202e],
     [0x2060, 0x206f],
     [0x20d0, 0x20f0],
@@ -233,9 +233,9 @@ const ZERO_RANGES = [
     [0xabe8, 0xabe8],
     [0xabed, 0xabed],
     [0xfb1e, 0xfb1e],
-    [0xfe00, 0xfe0f],
-    [0xfe20, 0xfe2f],
-    [0xfeff, 0xfeff],
+    [0xfe00, 0xfe0f], // variation selectors
+    [0xfe20, 0xfe2f], // combining half-marks
+    [0xfeff, 0xfeff], // BOM
     [0xfff9, 0xfffb],
     [0x101fd, 0x101fd],
     [0x102e0, 0x102e0],
@@ -342,15 +342,15 @@ export const padToWidth = (text, width, alignment) => {
 // divergences — we previously right-aligned interval & pg_lsn and omitted
 // xid & cid).
 const RIGHT_ALIGNED_OIDS = new Set([
-    20,
-    21,
-    23,
-    26,
-    28,
-    29,
-    700,
-    701,
-    790,
+    20, // int8
+    21, // int2
+    23, // int4
+    26, // oid
+    28, // xid
+    29, // cid
+    700, // float4
+    701, // float8
+    790, // money (cash)
     1700, // numeric
 ]);
 const isRightAlignedField = (oid) => RIGHT_ALIGNED_OIDS.has(oid);

package/psql/print/json.js

@@ -22,11 +22,11 @@
 // PostgreSQL type OIDs for the numeric family that map cleanly to
 // JSON numbers. NUMERIC is included but guarded by isFinite().
 const NUMERIC_TYPE_OIDS = new Set([
-    21,
-    23,
-    20,
-    700,
-    701,
+    21, // INT2
+    23, // INT4
+    20, // INT8
+    700, // FLOAT4
+    701, // FLOAT8
     1700, // NUMERIC
 ]);
 export const jsonPrinter = {

package/psql/scanner/sql.js

@@ -142,10 +142,10 @@ const cloneState = (s) => ({
 // blocks, dollar-quoted bodies). Identifier letters are stored lower-cased.
 // ---------------------------------------------------------------------------
 const KEYWORD_PREFIX_LETTERS = new Set([
-    'c',
-    'f',
-    'p',
-    'o',
+    'c', // create
+    'f', // function
+    'p', // procedure
+    'o', // or
     'r', // replace
 ]);
 const PREFIX_MATCHES_CREATE_FN_OR_PROC = (letters) => {