neonctl 2.23.1 → 2.24.0

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/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.1",
+  "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) => {