neonctl 2.37.0 → 2.38.0

package/dist/psql/command/cmd_meta.js

@@ -1,969 +0,0 @@
-/**
- * Meta backslash commands.
- *
- * TypeScript port of the corresponding `exec_command_*` functions in
- * upstream PostgreSQL's `src/bin/psql/command.c`:
- *
- *   - `\q` / `\quit`              → exec_command_quit
- *   - `\r` / `\reset`             → exec_command_reset
- *   - `\!`                        → exec_command_shell_escape (do_shell)
- *   - `\cd`                       → exec_command_cd
- *   - `\echo`, `\qecho`, `\warn`  → exec_command_echo / qecho / warn
- *   - `\prompt`                   → exec_command_prompt
- *   - `\set`, `\unset`            → exec_command_set / exec_command_unset
- *   - `\getenv`, `\setenv`        → exec_command_getenv / exec_command_setenv
- *   - `\errverbose`               → exec_command_errverbose
- *   - `\timing`                   → exec_command_timing
- *   - `\copyright`                → exec_command_copyright
- *   - `\h` / `\help`              → exec_command_help (helpSQL)
- *
- * Each command is exported as a `BackslashCmdSpec` so {@link defaultRegistry}
- * in `dispatch.ts` can register them. Error messages follow upstream's
- * `\<cmd>: <message>` shape and go to stderr; on failure we return
- * `{ status: 'error' }`. Successful invocations return `{ status: 'ok' }`.
- *
- * Stubs / deferred behaviour:
- *
- *   - `\!` always returns `{ status: 'ok' }` — upstream does not propagate
- *     the child's exit status to the surrounding script, only the run-mode.
- *     Tests use a stdio mock; in interactive use the child inherits stdio.
- *   - `\prompt -` (no-echo password prompting) reads via the shared input
- *     layer with echo suppressed on a TTY (falling back to a plain read on
- *     non-interactive input).
- *   - `\qecho` writes to `settings.logfile` if set, else stdout. Upstream
- *     additionally honours a separate "query output" file set via `\o`;
- *     that wiring lives in WP-15 and we leave the hook in place.
- */
-import { spawnSync } from "node:child_process";
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { helpSQL, slashUsage } from "../core/help.js";
-import { getHistory } from "../io/history.js";
-import { readLine } from "../io/input.js";
-import { parseBool, writeErr, writeOut } from "./shared.js";
-/** `\q` / `\quit` — exit the REPL. */
-export const cmdQuit = {
-    name: "q",
-    aliases: ["quit"],
-    helpKey: "q",
-    run: () => Promise.resolve({ status: "exit" }),
-};
-/**
- * `\!` — shell escape. Whole-line mode: the entire rest of the line is the
- * command string.
- *
- *   - `\!` (no args)             → spawn `$SHELL -i` (fallback `sh -i`)
- *   - `\!command args`           → spawn `sh -c 'command args'`
- *
- * In both cases the child inherits stdio and we return `{ status: 'ok' }`
- * regardless of the child's exit status — matching upstream `do_shell`,
- * which keeps the REPL alive after a failing shell command rather than
- * propagating the exit code. Catching a spawn-time exception keeps us
- * resilient against environments where `sh` is unavailable.
- */
-export const cmdShell = {
-    name: "!",
-    argMode: "whole-line",
-    helpKey: "!",
-    run: (ctx) => {
-        const line = ctx.restOfLine().trim();
-        try {
-            if (line.length === 0) {
-                const shell = process.env.SHELL ?? "/bin/sh";
-                spawnSync(shell, ["-i"], { stdio: "inherit" });
-            }
-            else {
-                spawnSync("sh", ["-c", line], { stdio: "inherit" });
-            }
-        }
-        catch {
-            // Upstream `do_shell` swallows shell-spawn failures: the REPL has to
-            // keep running even when the child won't start. Status stays `ok` so
-            // a failing `\!` is purely informational.
-        }
-        return Promise.resolve({ status: "ok" });
-    },
-};
-/** `\cd [dir]` — change cwd. No arg falls back to `$HOME`. */
-export const cmdCd = {
-    name: "cd",
-    helpKey: "cd",
-    run: (ctx) => {
-        const dir = ctx.nextArg("normal");
-        const target = dir && dir.length > 0 ? dir : (process.env.HOME ?? null);
-        if (!target) {
-            writeErr(`\\${ctx.cmdName}: could not determine home directory\n`);
-            return Promise.resolve({ status: "error" });
-        }
-        try {
-            process.chdir(target);
-            return Promise.resolve({ status: "ok" });
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            writeErr(`\\${ctx.cmdName}: ${msg}\n`);
-            return Promise.resolve({ status: "error" });
-        }
-    },
-};
-/**
- * Helper for `\echo` / `\qecho` / `\warn`. Reads args until exhausted,
- * honours the leading `-n` flag (suppresses trailing newline), joins with
- * single spaces, and writes to the chosen stream.
- *
- * Upstream `exec_command_echo` only treats `-n` as a flag when the source
- * was the unquoted two-character token `-n`. `'-n'` (single-quoted) is a
- * literal value: it should be printed AND the trailing newline kept. We
- * inspect `ctx.rawArgs` directly because `nextArg` discards quote
- * metadata after lexing.
- */
-const runEcho = (ctx, write) => {
-    const parts = [];
-    let noNewline = false;
-    let first = true;
-    // Pre-scan the raw text to decide whether the first arg was the
-    // unquoted `-n` token. We can't rely on the lexed arg value alone:
-    // `'-n'` / `"-n"` produce the same string but must be treated as data.
-    const firstArgIsUnquotedDashN = (() => {
-        let i = 0;
-        while (i < ctx.rawArgs.length && /\s/.test(ctx.rawArgs[i]))
-            i++;
-        return (ctx.rawArgs.slice(i, i + 2) === "-n" &&
-            (i + 2 === ctx.rawArgs.length || /\s/.test(ctx.rawArgs[i + 2])));
-    })();
-    for (;;) {
-        const arg = ctx.nextArg("normal");
-        if (arg === null)
-            break;
-        if (first && firstArgIsUnquotedDashN && arg === "-n") {
-            noNewline = true;
-            first = false;
-            continue;
-        }
-        first = false;
-        parts.push(arg);
-    }
-    const out = parts.join(" ") + (noNewline ? "" : "\n");
-    write(out);
-    return { status: "ok" };
-};
-/** `\echo` — write args to stdout. */
-export const cmdEcho = {
-    name: "echo",
-    helpKey: "echo",
-    run: (ctx) => Promise.resolve(runEcho(ctx, writeOut)),
-};
-/** `\qecho` — write args to the query output (logfile if set, else stdout). */
-export const cmdQecho = {
-    name: "qecho",
-    helpKey: "qecho",
-    run: (ctx) => {
-        const { logfile } = ctx.settings;
-        const write = (s) => {
-            if (logfile) {
-                logfile.write(s);
-            }
-            else {
-                writeOut(s);
-            }
-        };
-        return Promise.resolve(runEcho(ctx, write));
-    },
-};
-/** `\warn` — write args to stderr. */
-export const cmdWarn = {
-    name: "warn",
-    helpKey: "warn",
-    run: (ctx) => Promise.resolve(runEcho(ctx, writeErr)),
-};
-/**
- * `\prompt [TEXT] varname`
- *
- * Upstream: read one line of input from the terminal, optionally with a
- * prompt prefix, and assign it to a psql variable. A leading `-` flag
- * requests a no-echo read (used for password prompts); we honour it by
- * reading through the shared input layer with echo suppressed on a TTY
- * (and a plain read otherwise — non-interactive input still consumes the
- * line, matching upstream).
- *
- * Args after the optional `-` flag are `[TEXT] varname`: if only one
- * remains it is the variable name and no prompt prefix is shown; if two,
- * the first is the prompt and the second the variable.
- */
-export const cmdPrompt = {
-    name: "prompt",
-    helpKey: "prompt",
-    run: async (ctx) => {
-        const args = [];
-        for (;;) {
-            const a = ctx.nextArg("normal");
-            if (a === null)
-                break;
-            args.push(a);
-        }
-        // A leading `-` selects the no-echo (password) read path.
-        let echo = true;
-        if (args.length > 0 && args[0] === "-") {
-            echo = false;
-            args.shift();
-        }
-        if (args.length === 0) {
-            writeErr(`\\${ctx.cmdName}: missing required argument\n`);
-            return { status: "error" };
-        }
-        let promptText = "";
-        let varname;
-        if (args.length === 1) {
-            varname = args[0];
-        }
-        else {
-            promptText = args[0];
-            varname = args[1];
-        }
-        const line = await readLine(promptText, { echo });
-        if (!ctx.settings.vars.set(varname, line)) {
-            writeErr(`\\${ctx.cmdName}: invalid variable name "${varname}"\n`);
-            return { status: "error" };
-        }
-        return { status: "ok" };
-    },
-};
-/**
- * `\set [varname [value...]]`
- *
- * - No args → list all variables (sorted, `name = 'value'` per line) to
- *   stdout. Upstream uses single-quotes around the value.
- * - One arg → set the variable to the empty string.
- * - More args → join the rest with a single space and set the variable.
- *
- * Diagnostics mirror upstream `exec_command_set` in `src/bin/psql/command.c`:
- *
- *   - Names containing characters outside `[A-Za-z_][A-Za-z0-9_]*` produce
- *     `invalid variable name: "<name>"` (prefixed with `psql: `).
- *   - Per-variable hook rejections (AUTOCOMMIT / FETCH_COUNT /
- *     ON_ERROR_ROLLBACK / VERBOSITY / etc.) carry the hook's message
- *     verbatim; we add only the `psql: ` prefix.
- *   - Hook vetoes with no message fall back to a generic line. This
- *     should not happen in practice — every registered hook either
- *     accepts or returns a wording string.
- */
-export const cmdSet = {
-    name: "set",
-    helpKey: "set",
-    run: (ctx) => {
-        const name = ctx.nextArg("normal");
-        if (name === null) {
-            // List all vars sorted by name.
-            const entries = [...ctx.settings.vars.entries()].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
-            for (const [k, v] of entries) {
-                writeOut(`${k} = '${v}'\n`);
-            }
-            return Promise.resolve({ status: "ok" });
-        }
-        const values = [];
-        for (;;) {
-            const a = ctx.nextArg("normal");
-            if (a === null)
-                break;
-            values.push(a);
-        }
-        const value = values.join("");
-        const result = ctx.settings.vars.trySet(name, value);
-        if (!result.ok) {
-            const prefix = psqlErrorPrefix(ctx.settings);
-            if (result.reason === "invalid-name") {
-                writeErr(`${prefix}invalid variable name: "${name}"\n`);
-            }
-            else if (result.error !== undefined) {
-                // Hook supplied its own wording — emit verbatim, prefixed with
-                // `psql: `. The message intentionally does NOT carry a severity
-                // (`error:` / `ERROR:`) because upstream's per-variable hooks
-                // also emit just `psql: <msg>` (see `bool_substitute_hook` etc.).
-                writeErr(`${prefix}${result.error}\n`);
-            }
-            else {
-                // Hook returned `false` without a message — fall back to a
-                // generic line so callers still see something. None of the
-                // built-in hooks take this path, but third-party callers might.
-                writeErr(`${prefix}error while setting variable "${name}"\n`);
-            }
-            return Promise.resolve({ status: "error" });
-        }
-        return Promise.resolve({ status: "ok" });
-    },
-};
-/**
- * `\r` / `\reset` — discard the accumulated query buffer.
- *
- * Mirrors upstream `exec_command_reset`:
- *
- *   resetPQExpBuffer(query_buf);
- *   psql_scan_reset(scan_state);
- *   if (!pset.quiet)
- *     puts(_("Query buffer reset (cleared)."));
- *
- * We model the buffer + scanner reset via `status: 'reset-buf'`; the
- * mainloop wipes `queryBuf` and re-initialises `scanState` when it sees
- * this. The diagnostic is gated on the `quiet` setting so `psql -q` (and
- * the regress harness, which passes `--quiet`) produces no output.
- */
-export const cmdReset = {
-    name: "r",
-    aliases: ["reset"],
-    helpKey: "r",
-    run: (ctx) => {
-        if (!ctx.settings.quiet) {
-            writeOut("Query buffer reset (cleared).\n");
-        }
-        return Promise.resolve({ status: "reset-buf", newBuf: "" });
-    },
-};
-/** `\unset varname` — unset a psql variable. */
-export const cmdUnset = {
-    name: "unset",
-    helpKey: "unset",
-    run: (ctx) => {
-        const name = ctx.nextArg("normal");
-        if (name === null) {
-            writeErr(`\\${ctx.cmdName}: missing required argument\n`);
-            return Promise.resolve({ status: "error" });
-        }
-        ctx.settings.vars.unset(name);
-        return Promise.resolve({ status: "ok" });
-    },
-};
-export const cmdGetenv = {
-    name: "getenv",
-    helpKey: "getenv",
-    run: (ctx) => {
-        const varname = ctx.nextArg("normal");
-        const envname = ctx.nextArg("normal");
-        if (varname === null || envname === null) {
-            writeErr(`\\${ctx.cmdName}: missing required argument\n`);
-            return Promise.resolve({ status: "error" });
-        }
-        const value = process.env[envname];
-        if (value === undefined) {
-            return Promise.resolve({ status: "ok" });
-        }
-        if (!ctx.settings.vars.set(varname, value)) {
-            writeErr(`\\${ctx.cmdName}: invalid variable name "${varname}"\n`);
-            return Promise.resolve({ status: "error" });
-        }
-        return Promise.resolve({ status: "ok" });
-    },
-};
-/**
- * `\setenv envvar [value]`
- *
- * Set `process.env[envvar] = value`; with no value, delete it. Upstream
- * rejects names containing `=`.
- */
-export const cmdSetenv = {
-    name: "setenv",
-    helpKey: "setenv",
-    run: (ctx) => {
-        const envname = ctx.nextArg("normal");
-        if (envname === null) {
-            writeErr(`\\${ctx.cmdName}: missing required argument\n`);
-            return Promise.resolve({ status: "error" });
-        }
-        if (envname.includes("=")) {
-            writeErr(`\\${ctx.cmdName}: environment variable name must not contain "="\n`);
-            return Promise.resolve({ status: "error" });
-        }
-        // Upstream `exec_command_setenv` reads BOTH the name AND the value with
-        // OT_NORMAL — `:VAR` substitution applies to the value so
-        // `\setenv FOO :BAR` propagates the psql-variable value into the env.
-        // (Earlier 'no-vars' was a misread; vanilla psql expands inside the
-        // value.) The mainloop context maintains a per-mode cursor, so using
-        // a single mode for both calls also keeps positional reads in sync —
-        // each cursor advances exactly once per call.
-        const value = ctx.nextArg("normal");
-        if (value === null) {
-            delete process.env[envname];
-        }
-        else {
-            process.env[envname] = value;
-        }
-        return Promise.resolve({ status: "ok" });
-    },
-};
-/**
- * Build the `psql:` diagnostic prefix that upstream `pg_log_pre_callback`
- * prepends to error lines, but ONLY when reading from a script file. Mirrors:
- *
- *   if (cur_cmd_source == QUERY_FROM_FILE)
- *       fprintf(stderr, "psql:%s:%d: ", cur_cmd_filename, cur_cmd_lineno);
- *
- *   - `curCmdSource === 'file'` (running under `-f FILE`, `\i FILE`,
- *     `\ir FILE`, or `.psqlrc`): `psql:<inputfile>:<lineno>: `.
- *   - Stdin pipe, `-c "..."`, interactive REPL: empty string — vanilla
- *     `psql --no-psqlrc -X` reading SQL from stdin emits NO prefix on
- *     either `\set` validation errors or server `ERROR:` lines.
- *
- * Returned string ends in a trailing space when non-empty so callers can
- * concatenate the severity directly (`prefix + 'ERROR:  msg'`).
- */
-export const psqlErrorPrefix = (settings, lineNumber) => {
-    if (settings.curCmdSource === "file" && settings.inputfile) {
-        const lineSuffix = lineNumber !== undefined ? String(lineNumber) : "";
-        return `psql:${settings.inputfile}:${lineSuffix}: `;
-    }
-    return "";
-};
-/**
- * Walk past leading whitespace + `--` line comments + slash-star block
- * comments at the head of `sqlText`. Returns the byte index of the first
- * "real" content character. Used by `renderLineAndCaret` to align the
- * `LINE N:` counter with upstream psql — vanilla strips these from the
- * buffer before `PQexec` (so the server's `position` is relative to the
- * trimmed buffer), but `captureLastError`/`normaliseSqlAndPosition` only
- * strips whitespace. Re-stripping here closes the gap when the captured
- * `sqlText` still carries leading `-- comment` lines (the common case
- * for SQL that the mainloop dispatched directly via `sendQuery`,
- * because that path doesn't pre-trim comments).
- *
- * Idempotent for already-trimmed input: if `sqlText` has no leading
- * prelude we return `0`, the caller takes the existing fast-path, and
- * the LINE count remains the count of newlines strictly before
- * `position - 1`.
- */
-const skipLeadingPrelude = (sqlText) => {
-    let i = 0;
-    const n = sqlText.length;
-    while (i < n) {
-        const c = sqlText.charCodeAt(i);
-        if (c === 0x20 ||
-            c === 0x09 ||
-            c === 0x0a ||
-            c === 0x0d ||
-            c === 0x0c ||
-            c === 0x0b) {
-            i++;
-            continue;
-        }
-        if (c === 0x2d && sqlText.charCodeAt(i + 1) === 0x2d) {
-            i += 2;
-            while (i < n && sqlText.charCodeAt(i) !== 0x0a)
-                i++;
-            continue;
-        }
-        if (c === 0x2f && sqlText.charCodeAt(i + 1) === 0x2a) {
-            i += 2;
-            let depth = 1;
-            while (i < n && depth > 0) {
-                if (sqlText.charCodeAt(i) === 0x2f &&
-                    sqlText.charCodeAt(i + 1) === 0x2a) {
-                    depth++;
-                    i += 2;
-                }
-                else if (sqlText.charCodeAt(i) === 0x2a &&
-                    sqlText.charCodeAt(i + 1) === 0x2f) {
-                    depth--;
-                    i += 2;
-                }
-                else {
-                    i++;
-                }
-            }
-            continue;
-        }
-        break;
-    }
-    return i;
-};
-/**
- * Render the `LINE N: …` re-print plus the `^` pointer underneath the
- * failing character, mirroring upstream psql's `report_error_query`
- * helper. Returns `null` when we don't have enough context (no SQL text
- * or no position) so the caller can skip the lines entirely.
- *
- * `position` is a 1-based character offset into `sqlText` (as delivered
- * in the server's `P` field). We pick the LINE containing that offset
- * and emit:
- *
- *     LINE N: <that line>
- *             ^
- *
- * The caret column is aligned to the offset within the picked line so
- * it points at the failing token. Trailing newlines on the picked line
- * are stripped so the `$` end-anchor in upstream's regex still matches.
- *
- * Leading whitespace + comments are skipped before computing the LINE
- * number so the count starts at the first content line — vanilla
- * advances past these before `PQexec`, so the server's `position` is
- * 1-based relative to a trimmed buffer; without the same skip here we'd
- * count newlines that vanilla never sent.
- *
- * Trailing-whitespace fix-up: callers in `cmd_io.ts` strip a `\g`-style
- * buffer's trailing whitespace before handing the SQL to `db.execSimple`
- * / `db.query`, so the server's `position` is relative to the trimmed
- * SQL while `sqlText` (used for the LINE echo) still carries the
- * trailing space(s). When `position` lands on trailing whitespace of
- * the LINE we picked — i.e., past `lineText.trimEnd().length` — that's
- * the "syntax error at end of input" case: vanilla sends the trailing
- * whitespace verbatim and the server reports a position one past the
- * full LINE length. Snap the caret to the end of `lineText` so our
- * output matches vanilla's `^` column. PostgreSQL's scanner never
- * emits positions pointing AT whitespace tokens (they're not lexed as
- * tokens), so the only realistic source of an "in trailing
- * whitespace" position is this trim-on-send delta.
- *
- * Exported so the per-statement error renderer in `core/common.ts` can
- * share the helper with `\errverbose`.
- */
-export const renderLineAndCaret = (sqlText, position) => {
-    if (!sqlText || !position)
-        return null;
-    const pos = parseInt(position, 10);
-    if (!Number.isFinite(pos) || pos <= 0)
-        return null;
-    // Advance past leading WS + comments so the LINE count starts at the
-    // first content line. The server's position is into the on-the-wire
-    // bytes — typically already past these, so rebasing keeps it inside
-    // the content range; if the rebased position would underflow we drop
-    // the LINE/caret block rather than mis-pointing.
-    const skip = skipLeadingPrelude(sqlText);
-    const trimmed = skip === 0 ? sqlText : sqlText.slice(skip);
-    const rebasedPos = pos - skip;
-    if (rebasedPos <= 0)
-        return null;
-    // The server's offset is 1-based and points at the failing character.
-    const idx = Math.min(rebasedPos - 1, trimmed.length);
-    // Find the line containing `idx`.
-    let lineStart = trimmed.lastIndexOf("\n", idx - 1);
-    lineStart = lineStart === -1 ? 0 : lineStart + 1;
-    let lineEnd = trimmed.indexOf("\n", lineStart);
-    if (lineEnd === -1)
-        lineEnd = trimmed.length;
-    const lineText = trimmed.slice(lineStart, lineEnd);
-    // Line number for the `LINE N:` prefix — 1-based.
-    const before = trimmed.slice(0, lineStart);
-    const lineNumber = (before.match(/\n/gu)?.length ?? 0) + 1;
-    // Column inside the picked line (0-based) where the `^` goes. Tabs
-    // upstream are expanded to a fixed width; we approximate with a
-    // single space so the pointer at least lands in the right ballpark.
-    let col = idx - lineStart;
-    // Snap past trailing whitespace when the position lands inside it —
-    // see the function header for the rationale (trim-on-send delta).
-    const lineTrimEndLen = lineText.replace(/[ \t\f\v]+$/u, "").length;
-    if (col >= lineTrimEndLen && col < lineText.length) {
-        col = lineText.length;
-    }
-    const caretIndent = " ".repeat(Math.max(0, col));
-    const prefix = `LINE ${String(lineNumber)}: `;
-    return {
-        line: `${prefix}${lineText}`,
-        caret: `${" ".repeat(prefix.length)}${caretIndent}^`,
-    };
-};
-/**
- * Render an ErrorResponse-shaped payload as the layered, verbosity-aware
- * report that upstream psql emits to stderr after a failed statement
- * (`PSQLExec` / `ProcessResult` in `src/bin/psql/common.c`).
- *
- * Returned array contains one element per logical line, without trailing
- * newlines — callers join with `\n` and write to their stream.
- *
- * Verbosity / SHOW_CONTEXT semantics, mirrored from upstream:
- *
- *   - `terse`: only the severity line (`<sev>:  <msg>`) is emitted.
- *
- *   - `default`: severity + message, plus `LINE N` / caret, DETAIL, HINT,
- *     STATEMENT (we omit STATEMENT — we never echo the query verbatim).
- *     CONTEXT and LOCATION are suppressed unless `SHOW_CONTEXT='always'`.
- *
- *   - `verbose`: adds the SQLSTATE prefix on the severity line, and
- *     CONTEXT plus LOCATION are unconditionally included when present.
- *
- *   - `sqlstate`: prepend the SQLSTATE on the severity line (same as
- *     `verbose`'s first line), but suppress LINE/DETAIL/HINT/CONTEXT/
- *     LOCATION. Matches the upstream "just give me the code" flavour.
- *
- * Empty server fields are skipped silently. The `LINE` / `^` pair only
- * appears when we have both originating SQL text and a 1-based position
- * pointing inside it.
- */
-export const formatErrorReport = (e, verbosity = "default", showContext = "errors") => {
-    const severity = e.severity ?? "ERROR";
-    const sqlstate = e.code ?? e.sqlstate ?? "XX000";
-    const message = e.message ?? "";
-    const out = [];
-    // `sqlstate` mode is the upstream "just give me the code" flavour:
-    // emit `<severity>:  <sqlstate>` with NO message body. `verbose` mode
-    // adds the SQLSTATE prefix and keeps the message + LINE/DETAIL/HINT
-    // layers below. Default/terse omit the SQLSTATE entirely.
-    //
-    // Reference: upstream `pg_log_pre_callback` / `PQresultErrorMessage`
-    // with `verbosity = PQERRORS_SQLSTATE`, which formats just
-    // `severity: sqlstate\n` and stops.
-    if (verbosity === "sqlstate") {
-        out.push(`${severity}:  ${sqlstate}`);
-        return out;
-    }
-    if (verbosity === "verbose") {
-        out.push(`${severity}:  ${sqlstate}: ${message}`);
-    }
-    else if (verbosity === "terse") {
-        // Terse suppresses LINE/caret/DETAIL/HINT/CONTEXT, but it merges the
-        // server's `position` into the severity line as `at character N` —
-        // matches libpq's `pqGetErrorNotice3` with `PQERRORS_TERSE` (and
-        // vanilla psql in the regress fixture). Only fires when position is a
-        // positive integer; the LINE/caret block below would have shown the
-        // same anchor for default verbosity.
-        const pos = e.position ? Number.parseInt(e.position, 10) : NaN;
-        if (Number.isFinite(pos) && pos > 0) {
-            out.push(`${severity}:  ${message} at character ${String(pos)}`);
-        }
-        else {
-            out.push(`${severity}:  ${message}`);
-        }
-        return out;
-    }
-    else {
-        out.push(`${severity}:  ${message}`);
-    }
-    const lineCaret = renderLineAndCaret(e.sqlText, e.position);
-    if (lineCaret) {
-        out.push(lineCaret.line);
-        out.push(lineCaret.caret);
-    }
-    if (e.detail)
-        out.push(`DETAIL:  ${e.detail}`);
-    if (e.hint)
-        out.push(`HINT:  ${e.hint}`);
-    // CONTEXT under default verbosity follows SHOW_CONTEXT: 'never' / 'errors'
-    // (the default — show on errors) / 'always'. We treat every call into the
-    // formatter as an error report, so 'errors' and 'always' both include
-    // CONTEXT, while 'never' suppresses it. Verbose verbosity unconditionally
-    // includes CONTEXT.
-    const includeContext = verbosity === "verbose" || showContext !== "never";
-    if (includeContext && e.where) {
-        out.push(`CONTEXT:  ${e.where}`);
-    }
-    if (verbosity === "verbose" && (e.routine || e.file || e.line)) {
-        const location = (e.routine ?? "") + (e.file ? `, ${e.file}:${e.line ?? ""}` : "");
-        out.push(`LOCATION:  ${location}`);
-    }
-    return out;
-};
-/**
- * `\errverbose` — print the last error in verbose form. We rely on the
- * mainloop to have stored `settings.lastErrorResult`; this command only
- * formats and prints. Without a saved error, upstream emits "There is no
- * previous error."
- *
- * Verbose output (PG 18 form):
- *
- *     ERROR:  <sqlstate>: <message>
- *     LINE N: <originating line of SQL>
- *             ^
- *     DETAIL:  <detail>
- *     HINT:  <hint>
- *     CONTEXT:  <where>
- *     LOCATION:  <routine>, <file>:<line>
- *
- * Empty fields are omitted. The `LINE` / `^` pair is only emitted when
- * we have both the originating SQL text and a server-provided position.
- */
-export const cmdErrverbose = {
-    name: "errverbose",
-    helpKey: "errverbose",
-    run: (ctx) => {
-        const e = ctx.settings.lastErrorResult;
-        if (!e || (!e.message && !e.sqlstate && !e.code)) {
-            // Upstream `exec_command_errverbose` writes the "no previous error"
-            // notice to stdout (via `printf`); only the verbose re-render goes to
-            // stderr (via `pg_log_error`).
-            writeOut("There is no previous error.\n");
-            return Promise.resolve({ status: "ok" });
-        }
-        // `\errverbose` always emits the full verbose form regardless of the
-        // currently active VERBOSITY setting. Output is prefixed with the same
-        // `psql:[<file>:<n>]:` tag upstream's `pg_log_pre_callback` adds — only
-        // on the leading severity line; subsequent layers (LINE / caret / DETAIL
-        // / HINT / LOCATION) stay unprefixed to match libpq's `PQresultErrorMessage`.
-        const lines = formatErrorReport(e, "verbose", "always");
-        const prefix = psqlErrorPrefix(ctx.settings);
-        const prefixed = [prefix + lines[0], ...lines.slice(1)];
-        writeErr(prefixed.join("\n") + "\n");
-        return Promise.resolve({ status: "ok" });
-    },
-};
-/**
- * `\timing [on|off]` — set `settings.timing`. With no arg the value is
- * flipped. Prints the new state to stdout. `toggle` is NOT a valid value —
- * upstream errors "Boolean expected" (review: minor divergences).
- */
-export const cmdTiming = {
-    name: "timing",
-    helpKey: "timing",
-    run: (ctx) => {
-        const arg = ctx.nextArg("normal");
-        let next;
-        if (arg === null) {
-            next = !ctx.settings.timing;
-        }
-        else {
-            const parsed = parseBool(arg);
-            if (parsed === null) {
-                writeErr(`\\${ctx.cmdName}: unrecognized value "${arg}" for "\\timing": Boolean expected\n`);
-                return Promise.resolve({ status: "error" });
-            }
-            next = parsed;
-        }
-        ctx.settings.timing = next;
-        writeOut(`Timing is ${next ? "on" : "off"}.\n`);
-        return Promise.resolve({ status: "ok" });
-    },
-};
-/**
- * Static text emitted by `\copyright`. Mirrors upstream psql's
- * `exec_command_copyright()` literal in `src/bin/psql/command.c`.
- */
-const COPYRIGHT_TEXT = `PostgreSQL Database Management System
-(formerly known as Postgres, then as Postgres95)
-
-Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
-
-Portions Copyright (c) 1994, The Regents of the University of California
-
-Permission to use, copy, modify, and distribute this software and its
-documentation for any purpose, without fee, and without a written agreement
-is hereby granted, provided that the above copyright notice and this
-paragraph and the following two paragraphs appear in all copies.
-
-IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR
-DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING
-LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION,
-EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
-SUCH DAMAGE.
-
-THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
-INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
-AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
-ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATIONS TO
-PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
-`;
-/**
- * neonctl-specific notice appended after the upstream PostgreSQL block.
- * This psql is a pure-TypeScript reimplementation embedded in neonctl, not
- * upstream psql — so we attribute it accordingly. No license claim is made
- * here on purpose (see the project's LICENSE file for terms).
- */
-const NEON_NOTICE = `
-This is an embedded psql reimplementation that ships with neonctl, the
-command-line interface for Neon (https://neon.tech). Neon is part of
-Databricks (https://www.databricks.com).
-
-It is an independent reimplementation of psql and is not affiliated with
-or endorsed by the PostgreSQL Global Development Group. See the neonctl
-LICENSE file for distribution terms.
-`;
-/**
- * `\copyright` — print the PostgreSQL copyright / license notice, followed
- * by a neonctl + Neon/Databricks attribution block. Takes no arguments.
- * The upstream block is preserved verbatim so the conformance regex
- * `/Copyright/` (from upstream `001_basic.pl` line 75) is satisfied; the
- * Neon notice is appended after it.
- */
-export const cmdCopyright = {
-    name: "copyright",
-    helpKey: "copyright",
-    run: () => {
-        writeOut(COPYRIGHT_TEXT + NEON_NOTICE);
-        return Promise.resolve({ status: "ok" });
-    },
-};
-/**
- * Terminal width used to lay out `\h` / `\help` topic lists. Upstream
- * uses `pset.popt.topt.envColumns` falling back to `ioctl(TIOCGWINSZ)`;
- * we read `process.stdout.columns` (Node populates this for TTYs) and
- * default to 80 if absent (non-TTY, piped output, etc.).
- */
-const screenWidth = () => {
-    const cols = process.stdout.columns;
-    return typeof cols === "number" && cols > 0 ? cols : 80;
-};
-/**
- * `\h [TOPIC]` (alias `\help`) — show SQL command help.
- *
- * Delegates to {@link helpSQL} in `core/help.ts`, passing the remainder
- * of the line as the topic. With no topic, prints the "Available help:"
- * overview; with a topic, prints the matching synopsis or a list of
- * matches. Mirrors upstream `exec_command_help` in `command.c`.
- */
-export const cmdHelpSQL = {
-    name: "h",
-    aliases: ["help"],
-    helpKey: "h",
-    run: (ctx) => {
-        // Upstream consumes the rest of the line in `OT_WHOLE_LINE` mode so
-        // multi-word topics like "CREATE TABLE" come through intact.
-        const topic = ctx.restOfLine();
-        helpSQL(process.stdout, topic.length === 0 ? null : topic, screenWidth());
-        return Promise.resolve({ status: "ok" });
-    },
-};
-/**
- * `\?` — show help for the backslash commands.
- *
- * Delegates to {@link slashUsage} in `core/help.ts`. We pass the output
- * stream (`process.stdout`) and request the pager only when that stream is
- * an interactive TTY — `slashUsage`/`emitHelp` re-check interactivity, but
- * gating the request here keeps the non-interactive path (scripts, piped
- * output, the regress harness) writing straight to stdout with no pager.
- *
- * Upstream `exec_command_help` reads `[commands|options|variables]`; we
- * mirror the default (backslash commands) form, which is the only variant
- * `\?` reaches without an argument. The remainder of the line is consumed
- * so a stray topic doesn't leak into the next command.
- */
-export const cmdSlashHelp = {
-    name: "?",
-    argMode: "whole-line",
-    helpKey: "?",
-    run: (ctx) => {
-        // Consume the rest of the line (`\? options`, `\? variables`) so the
-        // cursor doesn't strand trailing text; we only render the command help.
-        ctx.restOfLine();
-        const out = process.stdout;
-        const pager = Boolean(out.isTTY);
-        slashUsage(out, pager);
-        return Promise.resolve({ status: "ok" });
-    },
-};
-/**
- * Resolve the editor command psql would launch for `\e` / `\ef` / `\ev`,
- * mirroring upstream `editFile` / `get_alternate_expansion`:
- *
- *   $PSQL_EDITOR  ||  $EDITOR  ||  $VISUAL  ||  platform default
- *
- * The platform default is `notepad.exe` on Windows and `vi` elsewhere,
- * matching upstream's `DEFAULT_EDITOR`.
- */
-export const resolveEditor = (env = process.env) => {
-    const explicit = env.PSQL_EDITOR ?? env.EDITOR ?? env.VISUAL;
-    if (explicit !== undefined && explicit.length > 0)
-        return explicit;
-    return process.platform === "win32" ? "notepad.exe" : "vi";
-};
-/**
- * `\e` / `\edit [FILE] [LINE]` — edit the current query buffer (or a file)
- * in the user's editor, then load the edited text back into the query
- * buffer.
- *
- * This port implements the common no-FILE form: dump the current query
- * buffer to a temp file, spawn the editor on it inheriting stdio (upstream
- * `do_edit` → `editFile`), and on a clean exit read the file back and
- * return it as the new query buffer via `status: 'reset-buf'`. Upstream
- * strips a single trailing newline the editor may add; we do the same so
- * round-tripping an unchanged buffer is a no-op.
- *
- * Editor selection follows {@link resolveEditor}. The spawn uses
- * `spawnSync(..., { stdio: 'inherit' })` so the editor owns the terminal.
- * If the editor exits non-zero (or fails to spawn) we leave the buffer
- * untouched and report an error, matching upstream's behaviour of not
- * importing a failed edit.
- *
- * FILE / LINE arguments are accepted but the buffer is still seeded from
- * the current query buffer; a future WP can layer file-backed editing
- * (`\e file`) and `\ef`/`\ev` on top.
- */
-export const cmdEdit = {
-    name: "e",
-    aliases: ["edit"],
-    argMode: "whole-line",
-    helpKey: "e",
-    run: (ctx) => {
-        // We don't yet support `\e FILE`; consume the args so they don't strand.
-        ctx.restOfLine();
-        const editor = resolveEditor();
-        // psql seeds the temp file with the current query buffer. A trailing
-        // newline keeps editors that expect newline-terminated files happy.
-        const seed = ctx.queryBuf.length > 0 && !ctx.queryBuf.endsWith("\n")
-            ? ctx.queryBuf + "\n"
-            : ctx.queryBuf;
-        let dir = null;
-        try {
-            dir = mkdtempSync(join(tmpdir(), "psql.edit."));
-            const file = join(dir, "edit.sql");
-            writeFileSync(file, seed, "utf8");
-            const result = spawnSync(editor, [file], { stdio: "inherit" });
-            if (result.error ||
-                (result.status !== null && result.status !== 0)) {
-                const why = result.error
-                    ? result.error.message
-                    : `editor exited with status ${String(result.status)}`;
-                writeErr(`\\${ctx.cmdName}: ${why}\n`);
-                return Promise.resolve({ status: "error" });
-            }
-            let edited = readFileSync(file, "utf8");
-            // Upstream drops a single trailing newline the editor may have added
-            // so an unchanged round-trip restores the original buffer exactly.
-            if (edited.endsWith("\n"))
-                edited = edited.slice(0, -1);
-            return Promise.resolve({ status: "reset-buf", newBuf: edited });
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            writeErr(`\\${ctx.cmdName}: ${msg}\n`);
-            return Promise.resolve({ status: "error" });
-        }
-        finally {
-            if (dir) {
-                try {
-                    rmSync(dir, { recursive: true, force: true });
-                }
-                catch {
-                    // Temp-dir cleanup is best-effort; a leftover dir is harmless.
-                }
-            }
-        }
-    },
-};
-/**
- * `\s [FILENAME]` — print the command-line history, or save it to FILENAME.
- *
- * Mirrors upstream `exec_command_s` / `printHistory`:
- *
- *   - No argument: write the in-memory history (one entry per line) to
- *     stdout. Multi-line entries are printed verbatim (with their embedded
- *     newlines), matching readline's `\s` dump.
- *   - FILENAME given: write the same dump to that file. On success, and
- *     unless `\set QUIET` is in effect, print `Wrote history to file
- *     "<file>".` to stdout. On failure, emit the OS error to stderr and
- *     return an error.
- *
- * The history source is {@link getHistory}, the session's in-memory list
- * populated as each line is submitted (see `io/history.ts`).
- */
-export const cmdS = {
-    name: "s",
-    helpKey: "s",
-    run: (ctx) => {
-        const fname = ctx.nextArg("normal");
-        const entries = getHistory();
-        // Each entry is one logical command; readline's `\s` prints them one
-        // per line, so a trailing newline per entry reproduces that layout.
-        const body = entries.map((e) => e + "\n").join("");
-        if (fname === null || fname.length === 0) {
-            writeOut(body);
-            return Promise.resolve({ status: "ok" });
-        }
-        try {
-            writeFileSync(fname, body, "utf8");
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            writeErr(`\\${ctx.cmdName}: ${msg}\n`);
-            return Promise.resolve({ status: "error" });
-        }
-        if (!ctx.settings.quiet) {
-            writeOut(`Wrote history to file "${fname}".\n`);
-        }
-        return Promise.resolve({ status: "ok" });
-    },
-};