neonctl 2.23.1 → 2.24.1

package/dev/functions.js

@@ -0,0 +1,72 @@
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { loadConfigFromFile, resolveConfig, } from '@neondatabase/config';
+/**
+ * Load `neon.ts` (if any) and resolve the list of functions it declares into
+ * {@link PlannedFunction}s for `neon dev` to serve. Returns `null` when there is no
+ * `neon.ts` on the path from `cwd` up to the repo root — the caller turns that into a
+ * "no --source and no neon.ts" error.
+ *
+ * `branchName` is used only to evaluate a policy that switches on `branch.name`; the
+ * function list is otherwise branch-independent, so a placeholder is fine when unknown.
+ */
+export const resolveFunctionsFromConfig = async (cwd, branchName) => {
+    const loaded = await loadNeonConfig(cwd);
+    if (!loaded)
+        return null;
+    const { config, configDir, configPath } = loaded;
+    const resolved = resolveConfig(config, {
+        name: branchName ?? 'local',
+        exists: branchName !== undefined,
+    });
+    const functions = resolved.preview?.functions ?? [];
+    const planned = functions.map((fn) => {
+        const source = isAbsolute(fn.source)
+            ? fn.source
+            : resolve(configDir, fn.source);
+        if (!existsSync(source)) {
+            throw new Error(`Function "${fn.slug}" points at a source that does not exist: ${source} ` +
+                `(from neon.ts "${fn.source}"). Fix the source path and re-run.`);
+        }
+        return {
+            slug: fn.slug,
+            name: fn.name,
+            source,
+            portless: fn.dev?.portless === true,
+            ...(devPort(fn.dev) !== undefined
+                ? { port: devPort(fn.dev) }
+                : {}),
+            env: { ...fn.env },
+        };
+    });
+    return { configPath, functions: planned };
+};
+/**
+ * Read the `port` off a {@link FunctionDevConfig}. The discriminated union guarantees a
+ * `port` is present whenever `portless` is true, so this is `undefined` only for the
+ * non-portless, port-omitted case (the supervisor then searches for a free port).
+ */
+const devPort = (dev) => dev?.port;
+/**
+ * Load a `neon.ts` policy if one exists, returning the loaded config, the resolved path to
+ * the config file (used by the dev server to watch it), and the directory it lives in (used
+ * to resolve each function's relative `source`). Returns `null` when no config file is
+ * found; surfaces real load errors (e.g. a syntax error).
+ */
+const loadNeonConfig = async (cwd) => {
+    try {
+        const { config, resolvedPath } = await loadConfigFromFile({ cwd });
+        return {
+            config,
+            configDir: dirname(resolvedPath),
+            configPath: resolvedPath,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (/Could not find a Neon config file/i.test(message)) {
+            return null;
+        }
+        throw err;
+    }
+};

package/dev/inputs.js

@@ -0,0 +1,63 @@
+import { resolve } from 'node:path';
+const defaultDeps = {
+    isPackaged: () => process.pkg !== undefined,
+    loadEsbuild: (name) => import(name),
+};
+/**
+ * Resolve the exact set of files esbuild reads to produce the bundle for
+ * `source` — the entry plus every local module it imports (npm deps are left
+ * external, so they never appear). These are the files the dev watcher should
+ * watch, so a single edit triggers exactly one rebuild.
+ *
+ * Returns absolute paths, or `null` when the precise set cannot be computed —
+ * either inside the packaged binary (which cannot import esbuild as a module;
+ * it shells out to a binary that has no JSON-metafile equivalent here) or on a
+ * platform where the esbuild module won't load. Callers fall back to a coarser
+ * watch in that case.
+ *
+ * This performs a metafile-only pass (`write:false`, `metafile:true`) so it
+ * never emits output; the actual bundle bytes still come from `bundleEntry`.
+ */
+export const resolveWatchInputs = async (source, deps = defaultDeps) => {
+    if (deps.isPackaged())
+        return null;
+    // esbuild is resolved by a COMPUTED specifier, never the literal string
+    // 'esbuild', for the same reason as src/utils/esbuild.ts: rollup and
+    // @yao-pkg/pkg statically scan for literal import()/require() and would pull
+    // esbuild's native Go binary into the bundle/snapshot. Keep it invisible.
+    const name = ['es', 'build'].join('');
+    let esbuild;
+    try {
+        esbuild = await deps.loadEsbuild(name);
+    }
+    catch {
+        return null;
+    }
+    let metafile;
+    try {
+        // Mirrors bundleEntry's flags so the resolved input graph matches the real
+        // bundle. metafile:true + write:false makes this a pure analysis pass.
+        const result = await esbuild.build({
+            entryPoints: [source],
+            bundle: true,
+            write: false,
+            metafile: true,
+            format: 'esm',
+            platform: 'node',
+            packages: 'external',
+            logLevel: 'silent',
+        });
+        metafile = result.metafile;
+    }
+    catch {
+        // A bundle error here is non-fatal for watching: bundleEntry surfaces the
+        // real diagnostic. Fall back to the coarser watch so edits still rebuild.
+        return null;
+    }
+    const inputs = metafile?.inputs;
+    if (!inputs)
+        return null;
+    // metafile input keys are paths relative to esbuild's cwd; resolve to absolute
+    // so they compare cleanly against chokidar's watched paths.
+    return Object.keys(inputs).map((p) => resolve(process.cwd(), p));
+};

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/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.1",
   "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/pkg.js

@@ -1,3 +1,25 @@
 import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-export default JSON.parse(readFileSync(fileURLToPath(new URL('./package.json', import.meta.url)), 'utf-8'));
+/**
+ * Load the CLI's package.json for version metadata. In the built CLI it sits right next to
+ * this module (the build copies it into `dist`); when running from source (tests, `tsx`) it
+ * does not, so we walk up to the nearest `package.json`. Both layouts resolve to the same
+ * file, keeping `pkg.version` correct everywhere without a test-only shim.
+ */
+const loadPkg = () => {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (;;) {
+        try {
+            return JSON.parse(readFileSync(join(dir, 'package.json'), 'utf-8'));
+        }
+        catch {
+            const parent = dirname(dir);
+            if (parent === dir) {
+                throw new Error('Could not locate package.json for version detection.');
+            }
+            dir = parent;
+        }
+    }
+};
+export default loadPkg();

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,