neon 3.0.0 → 3.1.1

package/dist/psql/core/mainloop.js

@@ -1,1360 +1,749 @@
-/**
- * psql REPL main loop.
- *
- * TypeScript port of `MainLoop()` in `src/bin/psql/mainloop.c`. Drives the
- * read-eval-print cycle: read a line, feed it to the SQL scanner, dispatch
- * SQL or backslash commands as boundaries appear, print results, and loop.
- *
- * Simplifications vs upstream (each tracked against the WP plan):
- *
- *  - Line editing is delegated to `node:readline` for now. Upstream uses
- *    GNU readline / libedit for history and completion. The proper raw-mode
- *    line editor is owned by WP-24; until then we get sane prompt rendering
- *    and Ctrl-C handling for free from the standard library.
- *  - History accumulation is omitted (`pg_append_history` / `pg_send_history`
- *    in upstream). The history sink lives in WP-25.
- *  - `\COPY FROM STDIN` raw-data lines are not wired (WP-16). When that lands,
- *    the mainloop will switch to PROMPT3 and forward lines to a CopyInStream.
- *  - `\if`/`\elif`/`\else`/`\endif` dispatch is wired directly here so the
- *    cmd_cond module can stay decoupled from the dispatch registry. Other
- *    backslash commands go through the registry interface that WP-13 owns.
- *  - The transaction-state poll (`pset.statusF`/`PQtransactionStatus`) is
- *    represented by an optional `txStatus` field on Connection; if the
- *    Connection doesn't expose one we treat the state as `unknown` for
- *    prompt rendering.
- *
- * Tracked TODOs:
- *
- *  - PSQLRC startup script (WP-22).
- *  - Encoding / multibyte handling beyond UTF-8 (handled implicitly by JS).
- *  - `\watch` continuous-execution mode.
- */
-import * as readline from "node:readline";
-import { attachCondStack, COND_COMMAND_NAMES, cmdElif, cmdElse, cmdEndif, cmdIf, } from "../command/cmd_cond.js";
-import { consumeBindState, getPipelineState } from "../command/cmd_pipeline.js";
-import { consumeNext as consumeQueuedInput } from "../command/inputQueue.js";
+import { COND_COMMAND_NAMES, attachCondStack, cmdElif, cmdElse, cmdEndif, cmdIf } from "../command/cmd_cond.js";
+import { scanSlashArgs } from "../scanner/slash.js";
+import { formatDurationMs } from "../print/units.js";
+import { appendHistory, defaultHistoryPath, loadHistory, resolveHistSize, truncateHistory } from "../io/history.js";
+import { G as writeQueryError, H as renderResultSet, L as captureLastError, U as sendQuery, V as refreshErrorVars, f as consumeBindState, m as getPipelineState, z as pickOut } from "../../_chunks/cmd_pipeline-CUbBO9U_.js";
+import { consumeNext } from "../command/inputQueue.js";
 import { psqlCompleter } from "../complete/index.js";
-import { appendHistory, defaultHistoryPath, loadHistory, resolveHistSize, truncateHistory, } from "../io/history.js";
 import { LineEditor } from "../io/lineEditor/index.js";
-import { formatDurationMs } from "../print/units.js";
-import { scanSlashArgs } from "../scanner/slash.js";
-import { scanSql } from "../scanner/sql.js";
 import { initialScanState } from "../types/scanner.js";
-import { captureLastError, pickOut, refreshErrorVars, renderResultSet, sendQuery, writeQueryError, } from "./common.js";
+import { scanSql } from "../scanner/sql.js";
 import { renderPromptByName } from "./prompt.js";
-// ---------------------------------------------------------------------------
-// Exit codes — mirror psql's `EXIT_*` constants.
-// ---------------------------------------------------------------------------
-export const EXIT_SUCCESS = 0;
-export const EXIT_FAILURE = 1;
-export const EXIT_BADCONN = 2;
-export const EXIT_USER = 3;
-// ---------------------------------------------------------------------------
-// Built-in cond command map — these are dispatched directly, before the
-// registry lookup, because they must run even inside an inactive branch.
-// ---------------------------------------------------------------------------
-const COND_COMMANDS = new Map([
-    ["if", cmdIf],
-    ["elif", cmdElif],
-    ["else", cmdElse],
-    ["endif", cmdEndif],
+import * as readline from "node:readline";
+//#region src/psql/core/mainloop.ts
+/**
+* psql REPL main loop.
+*
+* TypeScript port of `MainLoop()` in `src/bin/psql/mainloop.c`. Drives the
+* read-eval-print cycle: read a line, feed it to the SQL scanner, dispatch
+* SQL or backslash commands as boundaries appear, print results, and loop.
+*
+* Simplifications vs upstream (each tracked against the WP plan):
+*
+*  - Line editing is delegated to `node:readline` for now. Upstream uses
+*    GNU readline / libedit for history and completion. The proper raw-mode
+*    line editor is owned by WP-24; until then we get sane prompt rendering
+*    and Ctrl-C handling for free from the standard library.
+*  - History accumulation is omitted (`pg_append_history` / `pg_send_history`
+*    in upstream). The history sink lives in WP-25.
+*  - `\COPY FROM STDIN` raw-data lines are not wired (WP-16). When that lands,
+*    the mainloop will switch to PROMPT3 and forward lines to a CopyInStream.
+*  - `\if`/`\elif`/`\else`/`\endif` dispatch is wired directly here so the
+*    cmd_cond module can stay decoupled from the dispatch registry. Other
+*    backslash commands go through the registry interface that WP-13 owns.
+*  - The transaction-state poll (`pset.statusF`/`PQtransactionStatus`) is
+*    represented by an optional `txStatus` field on Connection; if the
+*    Connection doesn't expose one we treat the state as `unknown` for
+*    prompt rendering.
+*
+* Tracked TODOs:
+*
+*  - PSQLRC startup script (WP-22).
+*  - Encoding / multibyte handling beyond UTF-8 (handled implicitly by JS).
+*  - `\watch` continuous-execution mode.
+*/
+const EXIT_SUCCESS = 0;
+const EXIT_FAILURE = 1;
+const EXIT_BADCONN = 2;
+const EXIT_USER = 3;
+const COND_COMMANDS = /* @__PURE__ */ new Map([
+	["if", cmdIf],
+	["elif", cmdElif],
+	["else", cmdElse],
+	["endif", cmdEndif]
 ]);
 const makeStreamLineReader = (input, out) => {
-    const rl = readline.createInterface({
-        input,
-        crlfDelay: Infinity,
-        terminal: false,
-    });
-    // We deliberately do NOT use rl[Symbol.asyncIterator]() here. Node's
-    // events.on()-based readline iterator races its own close: when the input
-    // stream EOFs after pushing many buffered lines, the iterator drains most
-    // of them correctly but on the boundary call (when the internal queue
-    // empties on the same tick the close completes) it calls
-    // Interface.resume() AFTER close has been applied, which throws
-    // `ERR_USE_AFTER_CLOSE: readline was closed` instead of returning
-    // `{ done: true }`. The previous, *successfully* buffered last `'line'`
-    // event ends up dropped. Reproduces in a standalone Node v24 program with
-    // ~2000 pushed lines followed by `push(null)`. The 'line' / 'close'
-    // event model below is queue-based so we never lose a line on close.
-    const lineQueue = [];
-    let waiter = null;
-    let ended = false;
-    rl.on("line", (line) => {
-        if (waiter) {
-            const w = waiter;
-            waiter = null;
-            w(line);
-        }
-        else {
-            lineQueue.push(line);
-        }
-    });
-    rl.on("close", () => {
-        ended = true;
-        if (waiter) {
-            const w = waiter;
-            waiter = null;
-            w(null);
-        }
-    });
-    return {
-        readLine: () => {
-            if (lineQueue.length > 0) {
-                return Promise.resolve(lineQueue.shift());
-            }
-            if (ended)
-                return Promise.resolve(null);
-            return new Promise((resolve) => {
-                waiter = resolve;
-            });
-        },
-        pushHistory: () => undefined,
-        // No prompt to garble; just write straight to stdout.
-        interject: (text) => {
-            out.write(text);
-        },
-        close: () => {
-            rl.close();
-            return Promise.resolve();
-        },
-    };
+	const rl = readline.createInterface({
+		input,
+		crlfDelay: Infinity,
+		terminal: false
+	});
+	const lineQueue = [];
+	let waiter = null;
+	let ended = false;
+	rl.on("line", (line) => {
+		if (waiter) {
+			const w = waiter;
+			waiter = null;
+			w(line);
+		} else lineQueue.push(line);
+	});
+	rl.on("close", () => {
+		ended = true;
+		if (waiter) {
+			const w = waiter;
+			waiter = null;
+			w(null);
+		}
+	});
+	return {
+		readLine: () => {
+			if (lineQueue.length > 0) return Promise.resolve(lineQueue.shift());
+			if (ended) return Promise.resolve(null);
+			return new Promise((resolve) => {
+				waiter = resolve;
+			});
+		},
+		pushHistory: () => void 0,
+		interject: (text) => {
+			out.write(text);
+		},
+		close: () => {
+			rl.close();
+			return Promise.resolve();
+		}
+	};
 };
 /**
- * Parse a psql VI_MODE-style boolean. Mirrors `ParseVariableBool` for the
- * common spellings: `on` / `true` / `yes` / `1` are truthy; `off` / `false` /
- * `no` / `0` are falsy; everything else returns `null` so the caller can
- * surface the upstream "invalid value" diagnostic.
- */
+* Parse a psql VI_MODE-style boolean. Mirrors `ParseVariableBool` for the
+* common spellings: `on` / `true` / `yes` / `1` are truthy; `off` / `false` /
+* `no` / `0` are falsy; everything else returns `null` so the caller can
+* surface the upstream "invalid value" diagnostic.
+*/
 const parseBoolVar = (raw) => {
-    const v = raw.toLowerCase().trim();
-    if (v === "" || v === "on" || v === "true" || v === "yes" || v === "1") {
-        return true;
-    }
-    if (v === "off" || v === "false" || v === "no" || v === "0") {
-        return false;
-    }
-    return null;
+	const v = raw.toLowerCase().trim();
+	if (v === "" || v === "on" || v === "true" || v === "yes" || v === "1") return true;
+	if (v === "off" || v === "false" || v === "no" || v === "0") return false;
+	return null;
 };
 /** Translate a psql VI_MODE var value into the LineEditor mode. */
 const viModeOption = (raw) => {
-    if (raw === undefined)
-        return "emacs";
-    return parseBoolVar(raw) === true ? "vi" : "emacs";
+	if (raw === void 0) return "emacs";
+	return parseBoolVar(raw) === true ? "vi" : "emacs";
 };
 const makeEditorLineReader = async (ctx, opts = {}) => {
-    const env = process.env;
-    const histPath = defaultHistoryPath(env);
-    const histSize = resolveHistSize(env);
-    const histControl = ctx.settings.vars.get("HISTCONTROL") ??
-        ctx.settings.histControl;
-    let history = [];
-    try {
-        history = await loadHistory(histPath);
-    }
-    catch {
-        // Missing or unreadable history file — start fresh.
-        history = [];
-    }
-    // VI_MODE: upstream readline's `set editing-mode {emacs|vi}`. We read once
-    // here for the initial mode, and below we install a VarStore hook so a
-    // subsequent `\set VI_MODE on` switches the editor at the next prompt.
-    const initialMode = viModeOption(ctx.settings.vars.get("VI_MODE"));
-    const editor = new LineEditor({
-        stdin: ctx.stdin,
-        stdout: ctx.stdout,
-        history,
-        completer: psqlCompleter({
-            settings: ctx.settings,
-            getQueryBuf: opts.getQueryBuf,
-        }),
-        mode: initialMode,
-    });
-    // Hook: validate the value, reject unrecognised input with psql's
-    // `\set: VI_MODE: invalid value "X"; valid values: on, off` diagnostic,
-    // and on success forward to `editor.setMode` (which defers the switch to
-    // the next readLine boundary). Replay on registration is fine — the hook
-    // is idempotent for a no-op `null`/unchanged value.
-    ctx.settings.vars.addHook("VI_MODE", (newValue) => {
-        if (newValue === null) {
-            editor.setMode("emacs");
-            return true;
-        }
-        const parsed = parseBoolVar(newValue);
-        if (parsed === null) {
-            ctx.stderr.write(`\\set: VI_MODE: invalid value "${newValue}"; valid values: on, off\n`);
-            return false;
-        }
-        editor.setMode(parsed ? "vi" : "emacs");
-        return true;
-    });
-    return {
-        readLine: async (prompt) => {
-            const r = await editor.readLine(prompt);
-            if (r === editor.EOF)
-                return null;
-            return r;
-        },
-        pushHistory: (line) => {
-            const trimmed = line.replace(/\n+$/, "");
-            if (trimmed.length === 0)
-                return;
-            editor.pushHistory(trimmed);
-            // Best-effort persist. We don't block the REPL on disk I/O.
-            void appendHistory(histPath, trimmed, histControl).catch(() => undefined);
-        },
-        interject: (text) => {
-            editor.interject(text);
-        },
-        close: async () => {
-            try {
-                editor.close();
-            }
-            catch {
-                // ignore
-            }
-            // Truncate to HISTSIZE on exit (libreadline behaviour).
-            try {
-                await truncateHistory(histPath, histSize);
-            }
-            catch {
-                // ignore
-            }
-        },
-    };
+	const env = process.env;
+	const histPath = defaultHistoryPath(env);
+	const histSize = resolveHistSize(env);
+	const histControl = ctx.settings.vars.get("HISTCONTROL") ?? ctx.settings.histControl;
+	let history = [];
+	try {
+		history = await loadHistory(histPath);
+	} catch {
+		history = [];
+	}
+	const initialMode = viModeOption(ctx.settings.vars.get("VI_MODE"));
+	const editor = new LineEditor({
+		stdin: ctx.stdin,
+		stdout: ctx.stdout,
+		history,
+		completer: psqlCompleter({
+			settings: ctx.settings,
+			getQueryBuf: opts.getQueryBuf
+		}),
+		mode: initialMode
+	});
+	ctx.settings.vars.addHook("VI_MODE", (newValue) => {
+		if (newValue === null) {
+			editor.setMode("emacs");
+			return true;
+		}
+		const parsed = parseBoolVar(newValue);
+		if (parsed === null) {
+			ctx.stderr.write(`\\set: VI_MODE: invalid value "${newValue}"; valid values: on, off\n`);
+			return false;
+		}
+		editor.setMode(parsed ? "vi" : "emacs");
+		return true;
+	});
+	return {
+		readLine: async (prompt) => {
+			const r = await editor.readLine(prompt);
+			if (r === editor.EOF) return null;
+			return r;
+		},
+		pushHistory: (line) => {
+			const trimmed = line.replace(/\n+$/, "");
+			if (trimmed.length === 0) return;
+			editor.pushHistory(trimmed);
+			appendHistory(histPath, trimmed, histControl).catch(() => void 0);
+		},
+		interject: (text) => {
+			editor.interject(text);
+		},
+		close: async () => {
+			try {
+				editor.close();
+			} catch {}
+			try {
+				await truncateHistory(histPath, histSize);
+			} catch {}
+		}
+	};
 };
 /**
- * Recognize upstream psql's `exit` / `quit` shortcut: when typed at the start
- * of a fresh statement (queryBuf empty), they exit the REPL. Accepts a
- * trailing `;` and/or whitespace.
- */
+* Recognize upstream psql's `exit` / `quit` shortcut: when typed at the start
+* of a fresh statement (queryBuf empty), they exit the REPL. Accepts a
+* trailing `;` and/or whitespace.
+*/
 const isQuitKeyword = (line) => {
-    const trimmed = line.trim();
-    if (trimmed.length === 0)
-        return false;
-    const stripped = trimmed.replace(/;+\s*$/u, "").trimEnd();
-    return stripped === "exit" || stripped === "quit";
+	const trimmed = line.trim();
+	if (trimmed.length === 0) return false;
+	const stripped = trimmed.replace(/;+\s*$/u, "").trimEnd();
+	return stripped === "exit" || stripped === "quit";
 };
 /**
- * Recognize the bare `help` keyword the same way upstream does: at the start
- * of a fresh statement, it prints a one-screen reminder of the most useful
- * meta-commands and continues the REPL.
- */
+* Recognize the bare `help` keyword the same way upstream does: at the start
+* of a fresh statement, it prints a one-screen reminder of the most useful
+* meta-commands and continues the REPL.
+*/
 const isHelpKeyword = (line) => {
-    const trimmed = line.trim();
-    if (trimmed.length === 0)
-        return false;
-    const stripped = trimmed.replace(/;+\s*$/u, "").trimEnd();
-    return stripped === "help";
+	const trimmed = line.trim();
+	if (trimmed.length === 0) return false;
+	return trimmed.replace(/;+\s*$/u, "").trimEnd() === "help";
 };
-const HELP_TEXT = "You are using psql-ts, the embedded TypeScript psql in neon.\n" +
-    "Type:  \\copyright for distribution terms\n" +
-    "       \\h for help with SQL commands\n" +
-    "       \\? for help with psql commands\n" +
-    "       \\g or terminate with semicolon to execute query\n" +
-    "       \\q to quit\n";
+const HELP_TEXT = "You are using psql-ts, the embedded TypeScript psql in neon.\nType:  \\copyright for distribution terms\n       \\h for help with SQL commands\n       \\? for help with psql commands\n       \\g or terminate with semicolon to execute query\n       \\q to quit\n";
 const makeLineReader = async (ctx, opts = {}) => {
-    const debug = process.env.NEONCTL_PSQL_DEBUG === "1";
-    if (ctx.settings.notty) {
-        if (debug) {
-            ctx.stderr.write("[psql-debug] notty=true; using stream reader (no line editor / no Tab completion)\n");
-        }
-        return makeStreamLineReader(ctx.stdin, ctx.stdout);
-    }
-    try {
-        const r = await makeEditorLineReader(ctx, opts);
-        if (debug) {
-            ctx.stderr.write("[psql-debug] LineEditor engaged (raw mode, Tab completion active)\n");
-        }
-        return r;
-    }
-    catch (err) {
-        if (debug) {
-            ctx.stderr.write(`[psql-debug] LineEditor setup failed, falling back to stream reader: ${err.message}\n`);
-        }
-        return makeStreamLineReader(ctx.stdin, ctx.stdout);
-    }
+	const debug = process.env.NEONCTL_PSQL_DEBUG === "1";
+	if (ctx.settings.notty) {
+		if (debug) ctx.stderr.write("[psql-debug] notty=true; using stream reader (no line editor / no Tab completion)\n");
+		return makeStreamLineReader(ctx.stdin, ctx.stdout);
+	}
+	try {
+		const r = await makeEditorLineReader(ctx, opts);
+		if (debug) ctx.stderr.write("[psql-debug] LineEditor engaged (raw mode, Tab completion active)\n");
+		return r;
+	} catch (err) {
+		if (debug) ctx.stderr.write(`[psql-debug] LineEditor setup failed, falling back to stream reader: ${err.message}\n`);
+		return makeStreamLineReader(ctx.stdin, ctx.stdout);
+	}
 };
 const transactionState = (ctx) => {
-    const db = ctx.settings.db;
-    if (!db)
-        return "idle";
-    const status = db.txStatus;
-    switch (status) {
-        case "I":
-        case "idle":
-            return "idle";
-        case "T":
-        case "in-block":
-            return "in-block";
-        case "E":
-        case "failed":
-            return "failed";
-        case "unknown":
-            return "unknown";
-        default:
-            return "idle";
-    }
+	const db = ctx.settings.db;
+	if (!db) return "idle";
+	switch (db.txStatus) {
+		case "I":
+		case "idle": return "idle";
+		case "T":
+		case "in-block": return "in-block";
+		case "E":
+		case "failed": return "failed";
+		case "unknown": return "unknown";
+		default: return "idle";
+	}
 };
-// ---------------------------------------------------------------------------
-// BackslashContext factory — built per-invocation so the dispatched command
-// sees an isolated arg-cursor.
-// ---------------------------------------------------------------------------
 const makeBackslashContext = (ctx, cmdName, rawArgs, queryBuf) => {
-    // Pre-parse the args once at construction. `nextArg` then pops from this
-    // queue. We over-parse a bit (every arg gets normalised through the slash
-    // scanner in 'normal' mode), then re-split for non-normal modes lazily on
-    // demand. For WP-12 the only consumers are the cond commands, which always
-    // request 'normal'; future WPs may need richer routing.
-    const varLookup = (name) => ctx.settings.vars.get(name);
-    const buffered = new Map();
-    const argsFor = (mode) => {
-        const cached = buffered.get(mode);
-        if (cached)
-            return cached;
-        const parsed = scanSlashArgs(rawArgs, mode, varLookup);
-        buffered.set(mode, parsed);
-        return parsed;
-    };
-    const cursors = new Map();
-    const bctx = {
-        settings: ctx.settings,
-        cmdName,
-        queryBuf,
-        rawArgs,
-        nextArg(mode = "normal") {
-            const args = argsFor(mode);
-            const idx = cursors.get(mode) ?? 0;
-            if (idx >= args.length)
-                return null;
-            cursors.set(mode, idx + 1);
-            return args[idx];
-        },
-        restOfLine() {
-            // Whatever the user typed after the command name, verbatim.
-            return rawArgs;
-        },
-    };
-    return bctx;
+	const varLookup = (name) => ctx.settings.vars.get(name);
+	const buffered = /* @__PURE__ */ new Map();
+	const argsFor = (mode) => {
+		const cached = buffered.get(mode);
+		if (cached) return cached;
+		const parsed = scanSlashArgs(rawArgs, mode, varLookup);
+		buffered.set(mode, parsed);
+		return parsed;
+	};
+	const cursors = /* @__PURE__ */ new Map();
+	return {
+		settings: ctx.settings,
+		cmdName,
+		queryBuf,
+		rawArgs,
+		nextArg(mode = "normal") {
+			const args = argsFor(mode);
+			const idx = cursors.get(mode) ?? 0;
+			if (idx >= args.length) return null;
+			cursors.set(mode, idx + 1);
+			return args[idx];
+		},
+		restOfLine() {
+			return rawArgs;
+		}
+	};
 };
-// ---------------------------------------------------------------------------
-// Error printing. Keeps the format close to libpq's `psql: ERROR:  msg`.
-// ---------------------------------------------------------------------------
 const writeError = (ctx, message) => {
-    ctx.stderr.write(`psql: ERROR:  ${message}\n`);
+	ctx.stderr.write(`psql: ERROR:  ${message}\n`);
 };
-// ---------------------------------------------------------------------------
-// Prompt context builder.
-// ---------------------------------------------------------------------------
 const buildPromptContext = (ctx, promptStatus, lineNumber) => ({
-    settings: ctx.settings,
-    cond: ctx.cond,
-    promptStatus,
-    lineNumber,
-    inTransaction: transactionState(ctx),
-    pipelineState: "off",
+	settings: ctx.settings,
+	cond: ctx.cond,
+	promptStatus,
+	lineNumber,
+	inTransaction: transactionState(ctx),
+	pipelineState: "off"
 });
-// ---------------------------------------------------------------------------
-// Conditional-command dispatch. Returns true if the command was a cond
-// command (handled here), false otherwise. cond commands run regardless of
-// whether the surrounding branch is active.
-// ---------------------------------------------------------------------------
 const dispatchCondCommand = async (ctx, cmdName, rawArgs, queryBuf) => {
-    const spec = COND_COMMANDS.get(cmdName);
-    if (!spec)
-        return { handled: false };
-    const bctx = makeBackslashContext(ctx, cmdName, rawArgs, queryBuf);
-    attachCondStack(bctx, ctx.cond);
-    const result = await spec.run(bctx);
-    // Only emit a fallback `psql: ERROR:  <msg>` line for commands that did
-    // NOT write their own diagnostic. The `errorWritten` flag distinguishes
-    // these: commands using cmd_io's `errResult` (and inline writers) set it
-    // to `true`; cond commands (which only stash `lastErrorResult.message`)
-    // leave it unset so the mainloop surfaces the message.
-    if (result.status === "error" &&
-        !result.errorWritten &&
-        ctx.settings.lastErrorResult?.message) {
-        writeError(ctx, ctx.settings.lastErrorResult.message);
-    }
-    return { handled: true, result };
+	const spec = COND_COMMANDS.get(cmdName);
+	if (!spec) return { handled: false };
+	const bctx = makeBackslashContext(ctx, cmdName, rawArgs, queryBuf);
+	attachCondStack(bctx, ctx.cond);
+	const result = await spec.run(bctx);
+	if (result.status === "error" && !result.errorWritten && ctx.settings.lastErrorResult?.message) writeError(ctx, ctx.settings.lastErrorResult.message);
+	return {
+		handled: true,
+		result
+	};
 };
-// ---------------------------------------------------------------------------
-// Backslash dispatch for non-cond commands. Only runs when cond is active.
-// Returns the BackslashResult, or null if no command was found.
-// ---------------------------------------------------------------------------
 const dispatchRegisteredCommand = async (ctx, cmdName, rawArgs, queryBuf) => {
-    const spec = ctx.registry.lookup(cmdName);
-    if (!spec) {
-        writeError(ctx, `invalid command \\${cmdName}`);
-        // Treat the "invalid command" message as already-written so the next
-        // layer doesn't add a second one. (Other dispatch paths set
-        // `lastErrorResult.message`; this one does not, so the duplicate
-        // guard below would skip anyway — flag it explicitly for symmetry.)
-        return { status: "error", errorWritten: true };
-    }
-    const bctx = makeBackslashContext(ctx, cmdName, rawArgs, queryBuf);
-    attachCondStack(bctx, ctx.cond);
-    const result = await spec.run(bctx);
-    // Same contract as `dispatchCondCommand`: only fall back to the bare
-    // `psql: ERROR:  <msg>` shape when the command didn't already surface
-    // its own diagnostic. Without this guard, `\gdesc` Parse failures
-    // would emit a stray `psql: ERROR:  <msg>` line between the LINE/`^`
-    // block and the `\errverbose` re-render, breaking the strict ordering
-    // check in the conformance regex.
-    if (result.status === "error" &&
-        !result.errorWritten &&
-        ctx.settings.lastErrorResult?.message) {
-        writeError(ctx, ctx.settings.lastErrorResult.message);
-    }
-    return result;
+	const spec = ctx.registry.lookup(cmdName);
+	if (!spec) {
+		writeError(ctx, `invalid command \\${cmdName}`);
+		return {
+			status: "error",
+			errorWritten: true
+		};
+	}
+	const bctx = makeBackslashContext(ctx, cmdName, rawArgs, queryBuf);
+	attachCondStack(bctx, ctx.cond);
+	const result = await spec.run(bctx);
+	if (result.status === "error" && !result.errorWritten && ctx.settings.lastErrorResult?.message) writeError(ctx, ctx.settings.lastErrorResult.message);
+	return result;
 };
-// ---------------------------------------------------------------------------
-// SendQuery — delegate to the unified pipeline in `common.ts`. Returns the
-// success flag so the read loop can short-circuit under ON_ERROR_STOP.
-//
-// If `\bind` (WP-21) has stashed parameters on the settings, route through
-// the extended-query path on the Connection. Otherwise use the simple-query
-// pipeline.
-// ---------------------------------------------------------------------------
 /**
- * Refresh psql vars that mirror connection-driven server state. Today this
- * is just `ENCODING` (tracks `client_encoding` ParameterStatus). Upstream
- * does the same check at the tail of `SendQuery` in common.c so a
- * `SET client_encoding = ...` lands on the psql var before the next
- * statement looks it up. Safe to call when no connection is bound.
- */
+* Refresh psql vars that mirror connection-driven server state. Today this
+* is just `ENCODING` (tracks `client_encoding` ParameterStatus). Upstream
+* does the same check at the tail of `SendQuery` in common.c so a
+* `SET client_encoding = ...` lands on the psql var before the next
+* statement looks it up. Safe to call when no connection is bound.
+*/
 const refreshConnectionVars = (ctx) => {
-    const db = ctx.settings.db;
-    if (!db)
-        return;
-    const enc = db.parameterStatus("client_encoding");
-    if (enc !== undefined && ctx.settings.vars.get("ENCODING") !== enc) {
-        ctx.settings.vars.set("ENCODING", enc);
-    }
+	const db = ctx.settings.db;
+	if (!db) return;
+	const enc = db.parameterStatus("client_encoding");
+	if (enc !== void 0 && ctx.settings.vars.get("ENCODING") !== enc) ctx.settings.vars.set("ENCODING", enc);
 };
 const dispatchSendQuery = async (ctx, sql) => {
-    // Always consume the bind stash up-front so it's cleared regardless of which
-    // branch runs (and regardless of success / failure on the bind path).
-    const bind = consumeBindState(ctx.settings);
-    // Pipeline-active routing: when `\startpipeline` is in effect, a
-    // semicolon-terminated SQL must be appended to the pipeline as
-    // Parse/Bind/Describe/Execute (no Sync). Sending it as a simple Query
-    // would corrupt the pipeline — the in-flight extended-protocol replies
-    // would land in `handleQueryMessage` and the pipeline's ResultSet
-    // promises would never settle, leaving `\endpipeline` hung.
-    //
-    // Mirrors upstream psql: `SendQuery` checks `PQpipelineStatus` and routes
-    // through `PQsendQueryParams`/`PQsendQuery` accordingly. We use the
-    // session helper so the wire enqueueing matches `\sendpipeline`.
-    const ps = getPipelineState(ctx.settings);
-    if (ps && ctx.settings.db) {
-        // Upstream `libpq` refuses `COPY ... FROM STDIN` / `COPY ... TO
-        // STDOUT` inside a pipeline with the fatal diagnostic
-        // "COPY in a pipeline is not supported, aborting connection".
-        // Detect, emit the same wording client-side, and tear down the
-        // connection so the mainloop's `checkConnectionLost` halt path
-        // fires for any subsequent statement (matching the upstream
-        // "aborting connection" semantics).
-        const trimmed = sql.trimStart();
-        if (/^COPY\b/i.test(trimmed) &&
-            /\b(FROM\s+STDIN|TO\s+STDOUT)\b/i.test(trimmed)) {
-            ctx.stderr.write("psql: error: COPY in a pipeline is not supported, aborting connection\n");
-            // Hard-abort the underlying socket so isClosed() flips true and the
-            // mainloop's post-dispatch `checkConnectionLost` ends the loop.
-            try {
-                const db = ctx.settings.db;
-                if (typeof db.abortForCopyInPipeline === "function") {
-                    db.abortForCopyInPipeline();
-                }
-                else if (typeof db.close === "function") {
-                    await db.close();
-                }
-            }
-            catch {
-                // ignore — the diagnostic has already been emitted.
-            }
-            return false;
-        }
-        try {
-            // Pipeline-mode `;`-queries: empty parameter list, anonymous prepared
-            // statement, anonymous portal. The result will surface later through
-            // `\endpipeline` / `\getresults`.
-            await ps.session.parse("", sql, []);
-            await ps.session.bind("", bind?.values ?? []);
-            const exec = (async () => {
-                await ps.session.execute("", 0);
-                return undefined;
-            })();
-            ps.pending.push(exec);
-            // The enqueue succeeded; the actual result will flush at
-            // `\endpipeline` time. Mark the diagnostic vars as success-now so
-            // intervening `\echo :ERROR` sees "false" between pipeline appends.
-            refreshErrorVars(ctx.settings, { kind: "success", rowCount: null });
-            return true;
-        }
-        catch (err) {
-            const message = captureLastError(ctx.settings, err, sql);
-            writeQueryError(ctx, message);
-            refreshErrorVars(ctx.settings, { kind: "error" });
-            return false;
-        }
-    }
-    if (bind && ctx.settings.db) {
-        const started = ctx.settings.timing ? Date.now() : 0;
-        let lastRowCount = null;
-        let hadError = false;
-        try {
-            const rs = await ctx.settings.db.query(sql, bind.values);
-            // Route the single ResultSet through the unified printer pipeline so
-            // `\bind` output looks identical to a simple-query result (and honours
-            // `\o FILE`, format selection, expanded mode, etc.).
-            const r = await renderResultSet(ctx, rs, pickOut(ctx));
-            lastRowCount = r.lastRowCount;
-            return true;
-        }
-        catch (err) {
-            // Capture the full ErrorResponse payload (severity / code / position /
-            // detail / hint / location) so the layered renderer can honour
-            // VERBOSITY and SHOW_CONTEXT exactly like the simple-query path.
-            const message = captureLastError(ctx.settings, err, sql);
-            writeQueryError(ctx, message);
-            hadError = true;
-            return false;
-        }
-        finally {
-            refreshConnectionVars(ctx);
-            refreshErrorVars(ctx.settings, hadError
-                ? { kind: "error" }
-                : { kind: "success", rowCount: lastRowCount });
-            if (ctx.settings.timing) {
-                ctx.stdout.write("\n" + formatDurationMs(Date.now() - started) + "\n");
-            }
-        }
-    }
-    const stats = await sendQuery(ctx, sql);
-    refreshConnectionVars(ctx);
-    return !stats.hadError;
+	const bind = consumeBindState(ctx.settings);
+	const ps = getPipelineState(ctx.settings);
+	if (ps && ctx.settings.db) {
+		const trimmed = sql.trimStart();
+		if (/^COPY\b/i.test(trimmed) && /\b(FROM\s+STDIN|TO\s+STDOUT)\b/i.test(trimmed)) {
+			ctx.stderr.write("psql: error: COPY in a pipeline is not supported, aborting connection\n");
+			try {
+				const db = ctx.settings.db;
+				if (typeof db.abortForCopyInPipeline === "function") db.abortForCopyInPipeline();
+				else if (typeof db.close === "function") await db.close();
+			} catch {}
+			return false;
+		}
+		try {
+			await ps.session.parse("", sql, []);
+			await ps.session.bind("", bind?.values ?? []);
+			const exec = (async () => {
+				await ps.session.execute("", 0);
+			})();
+			ps.pending.push(exec);
+			refreshErrorVars(ctx.settings, {
+				kind: "success",
+				rowCount: null
+			});
+			return true;
+		} catch (err) {
+			const message = captureLastError(ctx.settings, err, sql);
+			writeQueryError(ctx, message);
+			refreshErrorVars(ctx.settings, { kind: "error" });
+			return false;
+		}
+	}
+	if (bind && ctx.settings.db) {
+		const started = ctx.settings.timing ? Date.now() : 0;
+		let lastRowCount = null;
+		let hadError = false;
+		try {
+			const rs = await ctx.settings.db.query(sql, bind.values);
+			lastRowCount = (await renderResultSet(ctx, rs, pickOut(ctx))).lastRowCount;
+			return true;
+		} catch (err) {
+			const message = captureLastError(ctx.settings, err, sql);
+			writeQueryError(ctx, message);
+			hadError = true;
+			return false;
+		} finally {
+			refreshConnectionVars(ctx);
+			refreshErrorVars(ctx.settings, hadError ? { kind: "error" } : {
+				kind: "success",
+				rowCount: lastRowCount
+			});
+			if (ctx.settings.timing) ctx.stdout.write("\n" + formatDurationMs(Date.now() - started) + "\n");
+		}
+	}
+	const stats = await sendQuery(ctx, sql);
+	refreshConnectionVars(ctx);
+	return !stats.hadError;
 };
 /**
- * Format an async NotificationResponse (LISTEN/NOTIFY payload) the way
- * upstream's `PrintNotifications` in common.c does. Empty payloads omit the
- * payload clause for backward-compat with pre-9.0 servers.
- */
+* Format an async NotificationResponse (LISTEN/NOTIFY payload) the way
+* upstream's `PrintNotifications` in common.c does. Empty payloads omit the
+* payload clause for backward-compat with pre-9.0 servers.
+*/
 const formatNotification = (channel, payload, pid) => {
-    if (payload.length > 0) {
-        return (`Asynchronous notification "${channel}" with payload "${payload}" ` +
-            `received from server process with PID ${String(pid)}.\n`);
-    }
-    return (`Asynchronous notification "${channel}" ` +
-        `received from server process with PID ${String(pid)}.\n`);
+	if (payload.length > 0) return `Asynchronous notification "${channel}" with payload "${payload}" received from server process with PID ${String(pid)}.\n`;
+	return `Asynchronous notification "${channel}" received from server process with PID ${String(pid)}.\n`;
 };
 /**
- * Subscribe to NotificationResponse on the active connection, rendering each
- * to the REPL output (mirrors upstream `PrintNotifications` writing to
- * `pset.queryFout`). Returns the disposer the connection handed us, or
- * `null` when no connection is bound.
- */
+* Subscribe to NotificationResponse on the active connection, rendering each
+* to the REPL output (mirrors upstream `PrintNotifications` writing to
+* `pset.queryFout`). Returns the disposer the connection handed us, or
+* `null` when no connection is bound.
+*/
 const installNotificationHandler = (ctx, reader) => {
-    const db = ctx.settings.db;
-    if (!db)
-        return null;
-    return db.onNotification((channel, payload, pid) => {
-        // Route through the reader so the LineEditor (when raw-mode active)
-        // can clear / re-render its prompt block around the injected line.
-        // The stream-reader path treats interject as a plain stdout write.
-        reader.interject(formatNotification(channel, payload, pid));
-    });
+	const db = ctx.settings.db;
+	if (!db) return null;
+	return db.onNotification((channel, payload, pid) => {
+		reader.interject(formatNotification(channel, payload, pid));
+	});
 };
 /**
- * Render a NoticeResponse field the same way libpq's `pqBuildErrorMessage3`
- * does for the default `psql_notice_processor` (which is a thin
- * `fputs(msg, stderr)`). Mirrors VERBOSITY / SHOW_CONTEXT semantics:
- *
- *   - `terse` / `sqlstate`: just `<severity>:  <message>` (`sqlstate` also
- *     prepends the SQLSTATE on the severity line).
- *   - `default`: severity line + LINE/^ pointer + DETAIL/HINT, and CONTEXT
- *     when SHOW_CONTEXT is `always` (NOTICE is not an error, so the default
- *     `errors` setting suppresses its CONTEXT — upstream's libpq path
- *     gates context on `severity_nonlocalized == "ERROR"|"FATAL"|"PANIC"`).
- *   - `verbose`: full SQLSTATE / DETAIL / HINT / CONTEXT / LOCATION layers.
- *
- * The trailing newline mirrors libpq, so callers can `stderr.write()` the
- * returned string directly.
- */
+* Render a NoticeResponse field the same way libpq's `pqBuildErrorMessage3`
+* does for the default `psql_notice_processor` (which is a thin
+* `fputs(msg, stderr)`). Mirrors VERBOSITY / SHOW_CONTEXT semantics:
+*
+*   - `terse` / `sqlstate`: just `<severity>:  <message>` (`sqlstate` also
+*     prepends the SQLSTATE on the severity line).
+*   - `default`: severity line + LINE/^ pointer + DETAIL/HINT, and CONTEXT
+*     when SHOW_CONTEXT is `always` (NOTICE is not an error, so the default
+*     `errors` setting suppresses its CONTEXT — upstream's libpq path
+*     gates context on `severity_nonlocalized == "ERROR"|"FATAL"|"PANIC"`).
+*   - `verbose`: full SQLSTATE / DETAIL / HINT / CONTEXT / LOCATION layers.
+*
+* The trailing newline mirrors libpq, so callers can `stderr.write()` the
+* returned string directly.
+*/
 const formatNotice = (notice, verbosity, showContext) => {
-    const severity = notice.severity || "NOTICE";
-    const message = notice.message || "";
-    const lines = [];
-    if (verbosity === "verbose" || verbosity === "sqlstate") {
-        const sqlstate = notice.code ?? "XX000";
-        lines.push(`${severity}:  ${sqlstate}: ${message}`);
-    }
-    else {
-        lines.push(`${severity}:  ${message}`);
-    }
-    if (verbosity === "terse" || verbosity === "sqlstate") {
-        return lines.join("\n") + "\n";
-    }
-    if (notice.detail)
-        lines.push(`DETAIL:  ${notice.detail}`);
-    if (notice.hint)
-        lines.push(`HINT:  ${notice.hint}`);
-    // CONTEXT gating mirrors libpq's `pqBuildErrorMessage3`:
-    //   - `verbose` always includes CONTEXT
-    //   - `default` shows CONTEXT only when SHOW_CONTEXT is `always` for
-    //     non-error severities (NOTICE / WARNING / INFO / LOG / DEBUG), or
-    //     when SHOW_CONTEXT is `errors`/`always` for ERROR-level entries.
-    const isError = severity === "ERROR" || severity === "FATAL" || severity === "PANIC";
-    const includeContext = verbosity === "verbose" ||
-        showContext === "always" ||
-        (showContext === "errors" && isError);
-    if (includeContext && notice.where) {
-        lines.push(`CONTEXT:  ${notice.where}`);
-    }
-    if (verbosity === "verbose" && (notice.routine || notice.file)) {
-        const location = (notice.routine ?? "") +
-            (notice.file ? `, ${notice.file}:${notice.line ?? ""}` : "");
-        lines.push(`LOCATION:  ${location}`);
-    }
-    return lines.join("\n") + "\n";
+	const severity = notice.severity || "NOTICE";
+	const message = notice.message || "";
+	const lines = [];
+	if (verbosity === "verbose" || verbosity === "sqlstate") {
+		const sqlstate = notice.code ?? "XX000";
+		lines.push(`${severity}:  ${sqlstate}: ${message}`);
+	} else lines.push(`${severity}:  ${message}`);
+	if (verbosity === "terse" || verbosity === "sqlstate") return lines.join("\n") + "\n";
+	if (notice.detail) lines.push(`DETAIL:  ${notice.detail}`);
+	if (notice.hint) lines.push(`HINT:  ${notice.hint}`);
+	if ((verbosity === "verbose" || showContext === "always" || showContext === "errors" && (severity === "ERROR" || severity === "FATAL" || severity === "PANIC")) && notice.where) lines.push(`CONTEXT:  ${notice.where}`);
+	if (verbosity === "verbose" && (notice.routine || notice.file)) {
+		const location = (notice.routine ?? "") + (notice.file ? `, ${notice.file}:${notice.line ?? ""}` : "");
+		lines.push(`LOCATION:  ${location}`);
+	}
+	return lines.join("\n") + "\n";
 };
 /**
- * Subscribe to NoticeResponse on the active connection, rendering each to
- * stderr the way libpq's default `psql_notice_processor` does. Returns the
- * disposer the connection handed us, or `null` when no connection is bound.
- *
- * NOTICEs fire synchronously as the wire layer receives them, so an
- * inline `RAISE NOTICE` inside a `\;`-chained batch lands BEFORE the
- * tuples-producing portion of the batch is rendered — matching upstream
- * psql output.
- */
+* Subscribe to NoticeResponse on the active connection, rendering each to
+* stderr the way libpq's default `psql_notice_processor` does. Returns the
+* disposer the connection handed us, or `null` when no connection is bound.
+*
+* NOTICEs fire synchronously as the wire layer receives them, so an
+* inline `RAISE NOTICE` inside a `\;`-chained batch lands BEFORE the
+* tuples-producing portion of the batch is rendered — matching upstream
+* psql output.
+*/
 const installNoticeHandler = (ctx, reader) => {
-    const db = ctx.settings.db;
-    if (!db)
-        return null;
-    return db.onNotice((notice) => {
-        // Skip in pipeline mode: cmd_pipeline.ts's `\endpipeline` / `\getresults`
-        // re-renders each result's `notices[]` array via the per-result drain so
-        // the NOTICE lands AT the result boundary, not before. Emitting here too
-        // would duplicate every notice — once when the wire layer parses it,
-        // once when the drain walks `rs.notices`.
-        if (ctx.settings.sendMode === "extended-pipeline")
-            return;
-        const text = formatNotice(notice, ctx.settings.verbosity, ctx.settings.showContext);
-        // Notices go to stderr (libpq default). The LineEditor's prompt-redraw
-        // logic uses `interjectErr` to flush the message without disturbing the
-        // active prompt block — fall back to a raw stderr write when the reader
-        // doesn't expose that hook (stream / notty path).
-        const interjectErr = reader.interjectErr;
-        if (interjectErr) {
-            interjectErr.call(reader, text);
-        }
-        else {
-            ctx.stderr.write(text);
-        }
-    });
+	const db = ctx.settings.db;
+	if (!db) return null;
+	return db.onNotice((notice) => {
+		if (ctx.settings.sendMode === "extended-pipeline") return;
+		const text = formatNotice(notice, ctx.settings.verbosity, ctx.settings.showContext);
+		const interjectErr = reader.interjectErr;
+		if (interjectErr) interjectErr.call(reader, text);
+		else ctx.stderr.write(text);
+	});
 };
 const installSigint = (ctx, state) => {
-    const handler = () => {
-        if (state.inQuery && ctx.settings.db) {
-            // Best-effort cancel; ignore errors.
-            void ctx.settings.db.cancel().catch(() => undefined);
-            return;
-        }
-        state.resetBuf();
-    };
-    process.on("SIGINT", handler);
-    return () => process.off("SIGINT", handler);
+	const handler = () => {
+		if (state.inQuery && ctx.settings.db) {
+			ctx.settings.db.cancel().catch(() => void 0);
+			return;
+		}
+		state.resetBuf();
+	};
+	process.on("SIGINT", handler);
+	return () => process.off("SIGINT", handler);
 };
-// ---------------------------------------------------------------------------
-// The main entry point.
-// ---------------------------------------------------------------------------
-export const runMainLoop = async (ctx) => {
-    // queryBuf is declared up front so the line reader's tab completer can
-    // close over it via `getQueryBuf` and see the in-flight multi-line buffer
-    // on every Tab. The mainloop reassigns this variable across statements
-    // (resetBuf, after dispatch); the closure stays valid because it captures
-    // the binding, not a snapshot.
-    let queryBuf = "";
-    const reader = await makeLineReader(ctx, { getQueryBuf: () => queryBuf });
-    let scanState = initialScanState();
-    let stmtLineNumber = 1;
-    let successResult = EXIT_SUCCESS;
-    let exitRequested = false;
-    // Parallel stack of saved scanner states keyed to cond.depth(). Upstream
-    // `save_query_text_state` captures both `query_buf->len` AND the scanner
-    // state at the `\if` (and at each branch transition); `discard_query_text`
-    // restores both. The cond stack frame already carries `savedQueryBufLen`;
-    // we keep the matching scanState here so the cond commands stay decoupled
-    // from the scanner type. The two arrays are pushed / popped / re-anchored
-    // in lock-step with cond.push / cond.pop / cond.setSavedQueryBufLen.
-    const condScanStateStack = [];
-    const resetBuf = () => {
-        queryBuf = "";
-        scanState = initialScanState();
-        stmtLineNumber = 1;
-    };
-    // Detect mid-script connection loss and, on first detection, emit the
-    // upstream "connection to server was lost" diagnostic + flag EXIT_BADCONN.
-    // Subsequent statements would all rethrow against the closed connection;
-    // we halt the loop instead so we don't spam ERROR lines for every one.
-    const checkConnectionLost = () => {
-        if (ctx.settings.db?.isClosed()) {
-            ctx.stderr.write("psql: error: connection to server was lost\n");
-            successResult = EXIT_BADCONN;
-            exitRequested = true;
-            return true;
-        }
-        return false;
-    };
-    const sigintState = { inQuery: false, resetBuf };
-    const removeSigint = installSigint(ctx, sigintState);
-    // Seed the ENCODING psql var from the server's client_encoding the first
-    // time we enter the REPL — subsequent `SET client_encoding = ...` lands
-    // back through `refreshConnectionVars` after each query.
-    refreshConnectionVars(ctx);
-    // Subscribe to async NotificationResponse (LISTEN/NOTIFY) so a `NOTIFY foo`
-    // surfaces upstream's `Asynchronous notification "foo" ...` line. The
-    // disposer is run in the finally block at exit so we don't leak listeners.
-    const removeNotificationHandler = installNotificationHandler(ctx, reader);
-    // Subscribe to NoticeResponse so `RAISE NOTICE` / NOTICE DETAIL / `drop
-    // cascades` style server notices surface on stderr — matching libpq's
-    // default `psql_notice_processor`. Notices arrive synchronously during
-    // query execution, so inline `\;`-chain notices land at the right spot.
-    const removeNoticeHandler = installNoticeHandler(ctx, reader);
-    // Compute the prompt string for the current state. For notty input we emit
-    // the empty string so the stream reader doesn't see prompt bytes interleaved
-    // with stdout. For TTY input the LineEditor renders the prompt itself.
-    const computePrompt = (status) => {
-        if (ctx.settings.notty)
-            return "";
-        const name = queryBuf.trim().length === 0 || status === "ready"
-            ? "PROMPT1"
-            : status === "copy"
-                ? "PROMPT3"
-                : "PROMPT2";
-        const promptCtx = buildPromptContext(ctx, status, stmtLineNumber);
-        return renderPromptByName(name, promptCtx);
-    };
-    // Resolves a psql variable for `:NAME` substitution in SQL bodies.
-    // Backslash command bodies do their own expansion via `scanSlashArgs` in
-    // `makeBackslashContext`, so this lookup only fires inside scanSql.
-    const sqlVarLookup = (name) => ctx.settings.vars.get(name);
-    // Resolves a backslash-command's argument-mode hint so scanSql can
-    // consume the rest of the line correctly for whole-line / filepipe
-    // commands. Upstream's psqlscanslash.l flips between `<xslasharg>` and
-    // `<xslashwholeline>` based on the same hint — without it, the SQL
-    // scanner would terminate a `\!` or `\sf` arg at the next `\` (e.g.
-    // `\! whole_line \endif` would split into `\!` + `\endif`).
-    const slashCmdMode = (cmdName) => {
-        const spec = ctx.registry.lookup(cmdName);
-        if (!spec)
-            return undefined;
-        if (spec.argMode === "whole-line")
-            return "whole-line";
-        // Backslash registry currently only distinguishes whole-line vs the
-        // default `lex` mode. Filepipe is signalled per-call via
-        // `nextArg('filepipe')` inside cmd implementations rather than the
-        // spec, so we infer it from a small allow-list of commands that
-        // upstream declares as `OT_FILEPIPE` (`\w` and `\o`). Without this,
-        // `\w |/no/such/file \else` would split off `\else` as a separate
-        // command instead of capturing it as the file's whole-line arg.
-        if (cmdName === "w" || cmdName === "o")
-            return "filepipe";
-        return undefined;
-    };
-    /**
-     * Strip block / line comments cheaply before scanning so a COPY-shaped
-     * comment doesn't trigger pre-buffering or sink wiring.
-     */
-    const stripSqlComments = (sql) => sql.replace(/\/\*[\s\S]*?\*\//g, "").replace(/--[^\n]*/g, "");
-    /**
-     * Count the number of `COPY ... FROM STDIN` segments in `sql`. Upstream
-     * `handleCopyIn` in copy.c is invoked for each one that hits the wire as
-     * a `\;`-chained simple-query batch; the mainloop must pre-buffer the
-     * `\.`-terminated data block per occurrence and hand them to the wire
-     * layer before dispatch so CopyInResponse is satisfied without a
-     * blocking callback into the REPL.
-     *
-     * The regex tolerates the optional column list (`COPY t (a, b)`) and the
-     * format clause (`COPY t FROM STDIN WITH (...)` / `... CSV ...`). False
-     * positives inside string literals / comments are possible but extremely
-     * rare in scripted workloads — and a false positive only over-consumes
-     * lines from the input, which is recoverable. The conservative regex
-     * here matches upstream `psql`'s scanner heuristics closely enough for
-     * the conformance suite (`psql.sql` lines around 1467-1476).
-     */
-    const countCopyFromStdin = (sql) => {
-        const stripped = stripSqlComments(sql);
-        const re = /\bCOPY\b[\s\S]*?\bFROM\s+STDIN\b/giu;
-        let n = 0;
-        while (re.exec(stripped) !== null)
-            n += 1;
-        return n;
-    };
-    /**
-     * `true` when `sql` contains at least one `COPY ... TO STDOUT` segment.
-     * The wire layer routes mid-batch CopyData into our `copyOutMidBatchSink`
-     * when it's set; we install one for the duration of a batch that mentions
-     * `TO STDOUT` so the bytes land on the active output stream.
-     */
-    const hasCopyToStdout = (sql) => /\bCOPY\b[\s\S]*?\bTO\s+STDOUT\b/iu.test(stripSqlComments(sql));
-    /**
-     * Read one COPY-FROM-STDIN data block: consume lines from the reader
-     * until a bare `\.` arrives (or EOF / null). Returns the concatenated
-     * payload as a Buffer with trailing newlines preserved (the wire side
-     * sends the bytes verbatim; the server treats them as the COPY input).
-     * The `\.` terminator itself is NOT included.
-     */
-    const readCopyDataBlock = async () => {
-        const lines = [];
-        for (;;) {
-            const line = await reader.readLine("");
-            if (line === null)
-                break;
-            if (line.replace(/\s+$/, "") === "\\.")
-                break;
-            lines.push(line);
-            // Upstream `handleCopyIn` in copy.c reads COPY data lines straight
-            // off `copystream` with `fgets` and ships them to the server via
-            // `PQputCopyData` — there is no `--echo-all` branch on this path.
-            // Suppressing the echo here keeps the COPY-FROM-STDIN data out of
-            // the echo stream, matching vanilla: only the surrounding SQL
-            // statement (`COPY ... FROM STDIN`) lands in stdout, not its
-            // payload.
-        }
-        // Each line plus a trailing newline — matches the byte stream COPY
-        // expects on its input side.
-        const text = lines.length === 0 ? "" : lines.join("\n") + "\n";
-        return Buffer.from(text, "utf8");
-    };
-    /**
-     * Process the assembled queryBuf+line through scanSql, dispatching the
-     * boundaries it finds. Returns when we hit `incomplete`/`eof` and need
-     * the next input line.
-     */
-    const processChunk = async (chunk) => {
-        let working = chunk;
-        while (working.length > 0) {
-            // SINGLELINE (-S / `\set SINGLELINE on`): the scanner treats a top-level
-            // newline as an implicit `;`, so each input line dispatches on its own.
-            // Read the flag fresh each pass — `\set SINGLELINE` can flip it mid-REPL.
-            const result = scanSql(working, scanState, sqlVarLookup, slashCmdMode, {
-                singleline: ctx.settings.singleline,
-            });
-            scanState = result.nextState;
-            if (result.kind === "semicolon") {
-                // Use the substituted `result.sql` so `:NAME` references already
-                // resolved at scan time make it into the executed SQL.
-                const sqlText = queryBuf + result.sql;
-                queryBuf = "";
-                working = working.slice(result.consumed);
-                scanState = initialScanState();
-                stmtLineNumber = 1;
-                if (!ctx.cond.isActive()) {
-                    // Suppressed: discard, no execution, no error.
-                    continue;
-                }
-                // COPY ... FROM STDIN appearing as a segment of a `\;`-chained
-                // batch needs its CopyInResponse satisfied with the COPY data
-                // block(s) that follow on stdin. We pre-buffer one block per
-                // detected `FROM STDIN` occurrence and hand the bytes to the wire
-                // layer before dispatch. Mirrors upstream `handleCopyIn` in
-                // copy.c — except we pump the bytes up-front instead of via a
-                // callback into the REPL when CopyInResponse arrives.
-                const copyCount = ctx.settings.db
-                    ? countCopyFromStdin(sqlText)
-                    : 0;
-                const wantsCopyOut = ctx.settings.db !== undefined && hasCopyToStdout(sqlText);
-                if (copyCount > 0 && ctx.settings.db) {
-                    // The Connection type doesn't expose `queueCopyInData` (kept
-                    // off the frozen interface), but the concrete PgConnection
-                    // does. We duck-type the method to avoid coupling here.
-                    const conn = ctx.settings.db;
-                    if (typeof conn.queueCopyInData === "function") {
-                        // Drop any leftover buffers from a previous (failed) batch so
-                        // we don't accidentally re-use stale data.
-                        conn.clearCopyInDataQueue?.();
-                        for (let i = 0; i < copyCount; i += 1) {
-                            const block = await readCopyDataBlock();
-                            conn.queueCopyInData(block);
-                        }
-                    }
-                }
-                if (wantsCopyOut && ctx.settings.db) {
-                    // Wire a sink so the wire layer can forward mid-batch CopyData
-                    // bytes verbatim (matching `handleCopyOut`). Routes to the
-                    // active query output (`\o FILE` stashed stream when set,
-                    // otherwise `ctx.stdout`) — upstream `handleCopyOut` sinks the
-                    // bytes into `pset.queryFout`, which is whatever `\o` last
-                    // pointed at. Bytes already include trailing newlines on each
-                    // row, so we pass them through unchanged.
-                    const conn = ctx.settings.db;
-                    const out = pickOut(ctx);
-                    conn.copyOutMidBatchSink = (chunk) => {
-                        out.write(chunk);
-                    };
-                }
-                sigintState.inQuery = true;
-                const ok = await dispatchSendQuery(ctx, sqlText);
-                sigintState.inQuery = false;
-                // Always clear any leftover queued blocks once the batch settles
-                // (success or failure) so the next dispatch starts fresh.
-                if (copyCount > 0 && ctx.settings.db) {
-                    const conn = ctx.settings.db;
-                    conn.clearCopyInDataQueue?.();
-                }
-                if (wantsCopyOut && ctx.settings.db) {
-                    const conn = ctx.settings.db;
-                    conn.copyOutMidBatchSink = null;
-                }
-                // After any SQL statement, the server may have closed the connection
-                // (e.g. pg_terminate_backend on our own pid). Surface that once and
-                // halt — psql cannot recover from a lost connection mid-script.
-                if (checkConnectionLost())
-                    return;
-                if (!ok && ctx.settings.onErrorStop) {
-                    successResult = EXIT_USER;
-                    exitRequested = true;
-                    return;
-                }
-                continue;
-            }
-            if (result.kind === "backslash") {
-                // Fold buffered SQL accumulated before the backslash into queryBuf.
-                // `result.sql` carries the (possibly empty) text that preceded the
-                // backslash in this scan pass — empty when the backslash was at the
-                // top of the buffer, non-empty for shapes like
-                // `SELECT 1 \watch c=3` or `SELECT error\gdesc`. Buffer-consuming
-                // commands (\g, \gx, \gset, \gexec, \gdesc, \crosstabview, \watch,
-                // \bind) will read this through `BackslashContext.queryBuf` and
-                // return `reset-buf` to clear it; commands that don't care leave it
-                // intact for the next dispatch.
-                //
-                // Track whether this scan started cleanly: empty queryBuf and the
-                // backslash was at the head of `working`. In that case the slash
-                // command is the ENTIRE source line — the trailing `\n` left in
-                // `working` after the slice is just the line terminator, not an
-                // inter-line continuation separator. We need to drop it after
-                // dispatch so the next chunk's scanSql doesn't return an `eof`
-                // with `sql: '\n'` and accumulate a stray leading newline into
-                // the NEXT statement's queryBuf. Mirrors upstream `MainLoop()`'s
-                // `query_buf->len == added_nl_pos` strip (mainloop.c lines
-                // 480-484): when a line contains only a backslash command and
-                // the scanner added nothing to the buffer, the appended `\n` is
-                // taken back off so the buffer's `LINE N:` counting matches the
-                // user's mental model.
-                const slashOnlyLine = result.sql.length === 0 && queryBuf.length === 0;
-                queryBuf += result.sql;
-                working = working.slice(result.consumed);
-                const cmdName = result.cmd;
-                // Cond commands run unconditionally; everything else respects
-                // cond.isActive().
-                if (COND_COMMAND_NAMES.has(cmdName)) {
-                    // Snapshot scanState BEFORE the cond command runs — `\if` will
-                    // want the snapshot taken at its dispatch point (matches upstream
-                    // `save_query_text_state` capturing the scanner's input lexer
-                    // state). Cheap shallow copy: ScanState fields are primitives or
-                    // small immutable objects.
-                    const scanStateBefore = { ...scanState };
-                    const r = await dispatchCondCommand(ctx, cmdName, result.rest, queryBuf);
-                    if (r.handled && r.result?.status === "exit") {
-                        exitRequested = true;
-                        return;
-                    }
-                    // Cond commands implement upstream's `discard_query_text` via
-                    // the `truncateBufTo` field: when `\elif`/`\else`/`\endif`
-                    // leaves an INACTIVE branch, the SQL text the skipped branch
-                    // accumulated is rolled back to the snapshot captured at the
-                    // matching `\if`/`\elif`/`\else`. We also restore the scanner
-                    // state captured at that checkpoint — without this a `(` inside
-                    // the skipped branch would leave `parenDepth > 0` and the next
-                    // `;` wouldn't trigger a dispatch boundary. Stmt line number
-                    // stays as-is: the surrounding statement is still in flight.
-                    if (r.handled && r.result?.truncateBufTo !== undefined) {
-                        const target = r.result.truncateBufTo;
-                        if (target < queryBuf.length) {
-                            queryBuf = queryBuf.slice(0, target);
-                        }
-                        const savedScan = condScanStateStack[condScanStateStack.length - 1];
-                        if (savedScan !== undefined) {
-                            scanState = { ...savedScan };
-                        }
-                    }
-                    // Sync the parallel scan-state stack with whatever cond.push /
-                    // cond.pop / cond.setSavedQueryBufLen the command performed.
-                    // `\if`           → push the scan state captured at dispatch.
-                    // `\elif`/`\else` → replace the top entry with the scan state
-                    //                   that prevails AFTER any truncate-on-leaving-
-                    //                   inactive restoration (so the new branch
-                    //                   starts from a clean checkpoint).
-                    // `\endif`        → pop the top entry.
-                    if (cmdName === "if") {
-                        condScanStateStack.push(scanStateBefore);
-                    }
-                    else if (cmdName === "elif" || cmdName === "else") {
-                        // Errors leave the top untouched (cond.setState not called on
-                        // the no-matching/double-else paths). Only re-anchor when the
-                        // command succeeded — `status: 'ok'` covers both the active
-                        // and truncated paths.
-                        if (condScanStateStack.length > 0 &&
-                            r.result?.status === "ok") {
-                            condScanStateStack[condScanStateStack.length - 1] =
-                                {
-                                    ...scanState,
-                                };
-                        }
-                    }
-                    else if (cmdName === "endif") {
-                        // Pop only on success — `\endif` with no matching `\if`
-                        // returns an error and doesn't actually pop the cond frame.
-                        if (r.result?.status === "ok") {
-                            condScanStateStack.pop();
-                        }
-                    }
-                    // Note: we intentionally do NOT update `lastWasError` for cond
-                    // errors. Upstream psql exits 0 from a script whose only failure
-                    // was `\endif: no matching \if` (or any other cond diagnostic) —
-                    // these are printed and the loop continues, but they don't taint
-                    // the terminal `lastWasError → EXIT_USER` escalation. Only
-                    // ON_ERROR_STOP can escalate cond failures.
-                    if (r.handled &&
-                        r.result?.status === "error" &&
-                        ctx.settings.onErrorStop) {
-                        successResult = EXIT_USER;
-                        exitRequested = true;
-                        return;
-                    }
-                    continue;
-                }
-                // Upstream `HandleSlashCmds` looks up the command name BEFORE
-                // consulting the conditional stack: an unknown name emits
-                // `invalid command \X` to stderr regardless of branch state.
-                // Without this, e.g. `\if false \n \lo \n \endif` silently passes
-                // `\lo` through, but vanilla surfaces the diagnostic. Looking the
-                // command up here also lets us short-circuit the inactive branch
-                // without losing the unknown-command error.
-                if (!ctx.cond.isActive()) {
-                    if (ctx.registry.lookup(cmdName) === undefined) {
-                        // Bare wording (no `psql: ERROR:` prefix) — vanilla's
-                        // `psql_log_pre_callback` short-circuits when input has no
-                        // line-number context (stdin pipe path), so the diagnostic
-                        // is emitted via `pg_log_error_internal` as a raw string.
-                        // Matches the expected output's `invalid command \lo` shape
-                        // at psql.out:4698. Other writeError() call sites keep the
-                        // prefix because they're errors WE emit from a known
-                        // dispatch path, not from the unknown-command lookup miss.
-                        ctx.stderr.write(`invalid command \\${cmdName}\n`);
-                        // Errors emitted in an inactive branch must NOT taint
-                        // `lastWasError` (vanilla exits 0 from `\if false; \lo; \endif`)
-                        // and must NOT trigger ON_ERROR_STOP. The diagnostic stands
-                        // alone; the loop continues to the next chunk.
-                    }
-                    // Skip non-cond commands inside an inactive branch (run or not,
-                    // registered or not).
-                    continue;
-                }
-                const bres = await dispatchRegisteredCommand(ctx, cmdName, result.rest, queryBuf);
-                if (bres?.status === "exit") {
-                    exitRequested = true;
-                    return;
-                }
-                if (bres?.status === "reset-buf") {
-                    queryBuf = bres.newBuf ?? "";
-                    scanState = initialScanState();
-                    stmtLineNumber = 1;
-                    // The SQL scanner intentionally stops the backslash boundary on
-                    // (not past) the trailing line terminator so that an inter-line
-                    // `\n` separating a slash command from continuing SQL on the
-                    // next line survives in `working`. That's the right call when
-                    // the slash command leaves `queryBuf` intact — the `\n` keeps
-                    // line breaks in the assembled multi-line query.
-                    //
-                    // For `reset-buf`, however, the buffer is being intentionally
-                    // dropped: the slash command (`\g`, `\gset`, `\gdesc`, `\gexec`,
-                    // `\crosstabview`, `\watch`, `\bind`, `\parse`, …) has just
-                    // consumed and dispatched whatever was buffered. A residual
-                    // `\n` at the head of `working` is then leftover line-terminator
-                    // bytes from the slash-command line itself — NOT a continuation
-                    // separator. If we let it survive, the next scanSql pass returns
-                    // an `eof` with `sql: '\n'`, the loop's
-                    // `queryBuf += result.sql` line folds it into the NEXT
-                    // statement's buffer, and commands that store the buffer
-                    // verbatim (notably `\parse`, which uses the buffer text as the
-                    // prepared-statement source) emit a stray leading 0x0a byte.
-                    //
-                    // Strip the line terminator here so the next pass starts cleanly.
-                    // This matches upstream `psql_scan_slash_command_end()`'s eat-
-                    // through-newline behaviour for the buffer-reset case — without
-                    // changing the scanner's semantics for the inline-slash + multi-
-                    // line shape that depends on the `\n` surviving.
-                    if (working.startsWith("\r\n")) {
-                        working = working.slice(2);
-                    }
-                    else if (working.startsWith("\n") ||
-                        working.startsWith("\r")) {
-                        working = working.slice(1);
-                    }
-                }
-                // For status='ok' (the buffer was NOT consumed by the slash command),
-                // also drop the `\n` left in `working` when the slash command was
-                // the sole content of this source line. Upstream's
-                // `query_buf->len == added_nl_pos` strip (mainloop.c lines 480-484)
-                // covers the same shape: a line whose only token is a slash command
-                // doesn't contribute a `\n` to `query_buf`. Without this, e.g.
-                //   \set ECHO errors
-                //   SELECT * FROM bad;
-                // would assemble the SELECT's queryBuf as `\n` + `SELECT...` —
-                // shifting the server's `LINE N` count by one and contaminating
-                // the `STATEMENT:  ...` echo emitted on error.
-                if (bres?.status !== "reset-buf" && slashOnlyLine) {
-                    if (working.startsWith("\r\n")) {
-                        working = working.slice(2);
-                    }
-                    else if (working.startsWith("\n") ||
-                        working.startsWith("\r")) {
-                        working = working.slice(1);
-                    }
-                }
-                // Upstream `mainloop.c`: on PSQL_CMD_ERROR, the query buffer is
-                // reset and the scanner state is dropped. Mirrors `resetPQExpBuffer`
-                // + `psql_scan_reset`. Without this, a buffer-consuming command
-                // that fails (e.g. `SELECT 1 \watch 1 1` rejecting duplicate
-                // positional intervals) would leave `SELECT 1 ` in the buffer for
-                // the next prompt — and in notty mode the tail dispatch would
-                // execute it, masking the failure exit code.
-                //
-                // Upstream `HandleSlashCmds` additionally silently discards the
-                // remainder of the current line via `psql_scan_slash_option(scan_state,
-                // OT_WHOLE_LINE, …)` when a backslash command returns PSQL_CMD_ERROR.
-                // Mirror that here by dropping `working` up to and including the next
-                // newline. Without this, `\bind_named NAME 1 2 \gset pref02_ \echo X`
-                // would still execute `\echo X` after the pipeline-mode `\gset`
-                // rejection — vanilla suppresses it.
-                if (bres?.status === "error") {
-                    queryBuf = "";
-                    scanState = initialScanState();
-                    stmtLineNumber = 1;
-                    // Discard any trailing content on the SAME physical line — but NOT
-                    // the rest of the script. The scanner consumes a slash command's
-                    // args but typically leaves the line terminator (`\n`) at the head
-                    // of `working`. If `working` starts with `\n` / `\r\n`, the failed
-                    // command was already at end-of-line — just drop the terminator
-                    // and let the next line dispatch normally. If `working` has
-                    // non-newline chars before the next `\n`, drop up to and including
-                    // that `\n` (mirrors upstream `HandleSlashCmds`' `OT_WHOLE_LINE`
-                    // discard). Without this branch a stack of `\gdesc\n\gdesc\n…`
-                    // lines collapses to a single dispatched `\gdesc` because the
-                    // first discard ate the second line.
-                    if (working.startsWith("\r\n")) {
-                        working = working.slice(2);
-                    }
-                    else if (working.startsWith("\n") ||
-                        working.startsWith("\r")) {
-                        working = working.slice(1);
-                    }
-                    else {
-                        const nlIdx = working.indexOf("\n");
-                        working = nlIdx === -1 ? "" : working.slice(nlIdx + 1);
-                    }
-                }
-                // Backslash commands like \connect can also tear down the connection.
-                if (checkConnectionLost())
-                    return;
-                if (bres?.status === "error" && ctx.settings.onErrorStop) {
-                    successResult = EXIT_USER;
-                    exitRequested = true;
-                    return;
-                }
-                continue;
-            }
-            // incomplete or eof — keep accumulating. Use the substituted
-            // `result.sql` so `:NAME` tokens that were fully consumed in this
-            // chunk land in the buffer in expanded form. (A `:NAME` that
-            // straddles two chunks falls back to the literal — a corner case
-            // upstream also handles only when the variable name fits inside the
-            // current buffer; the line-reader feeds whole lines so this is
-            // effectively unreachable in interactive use.)
-            queryBuf += result.sql;
-            working = "";
-            return;
-        }
-    };
-    // -----------------------------------------------------------------------
-    // Read loop. Each iteration:
-    //   1. Drain any pending input enqueued by `\i FILE` (WP-15) — those lines
-    //      take precedence over fresh stdin so the include behaves as a
-    //      prepend on the input source.
-    //   2. Otherwise, ask the reader for the next line. For notty input this
-    //      is a `readline` stream; for TTY input it's the LineEditor with
-    //      emacs keybindings + persistent history (WP-24 + WP-25).
-    //   3. Each submitted line is recorded in history.
-    // -----------------------------------------------------------------------
-    try {
-        while (!exitRequested) {
-            // Prompt status drives `%R`. When the query buffer holds an incomplete
-            // statement but the scanner isn't inside any special context (paren,
-            // comment, quoted-string), it still reports `'ready'`; map that to
-            // `'continue'` so PROMPT2 renders `-` instead of `=`. A whitespace-only
-            // residue (e.g. a trailing `\n` left over after a `;` boundary) counts
-            // as empty so the next prompt is PROMPT1 not PROMPT2.
-            const status = queryBuf.trim().length === 0
-                ? "ready"
-                : scanState.promptStatus === "ready"
-                    ? "continue"
-                    : scanState.promptStatus;
-            const prompt = computePrompt(status);
-            // 1. Pending input from \i: process as a single chunk and loop again.
-            const queued = consumeQueuedInput();
-            if (queued !== null) {
-                await processChunk(queued.endsWith("\n") ? queued : queued + "\n");
-                continue;
-            }
-            // 2. Read the next line from stdin / line editor.
-            let line;
-            try {
-                line = await reader.readLine(prompt);
-            }
-            catch (err) {
-                // SignalError (Ctrl-C on an interactive line) — drop the partial
-                // buffer and re-prompt, matching upstream psql.
-                if (err.name === "SignalError") {
-                    resetBuf();
-                    continue;
-                }
-                throw err;
-            }
-            if (line === null)
-                break; // EOF
-            // Upstream `mainloop.c` MainLoop():
-            //
-            //   if (line[0] == '\0' && !psql_scan_in_quote(scan_state))
-            //   {
-            //       free(line);
-            //       continue;
-            //   }
-            //
-            // I.e., bare-empty lines are skipped entirely (no echo, no scanner
-            // pass) UNLESS the scanner is mid-quote (single-, double-, dollar-,
-            // or block-comment continuation). Inside a quote we keep the empty
-            // line so it lands in the assembled query buffer (e.g. a quoted
-            // identifier `"ab\n\nc"` spans multiple input lines including blanks),
-            // and `--echo-all` surfaces it so the echo stream tracks the source
-            // verbatim.
-            //
-            // `psql_scan_in_quote` returns true for all start_states except
-            // INITIAL and xqs — we approximate with the scanner-state fields
-            // that track each quoted construct. `parenDepth` is intentionally
-            // omitted (upstream doesn't count it as in-quote).
-            const scanInQuote = scanState.inBlockComment > 0 ||
-                scanState.inSingleQuote ||
-                scanState.inDoubleQuote ||
-                scanState.dollarTag !== null;
-            if (line.length === 0 && !scanInQuote) {
-                continue;
-            }
-            // 2'. ECHO=all — upstream `--echo-all` / `\set ECHO all` echoes every
-            // input line to stdout *before* it's processed. Blank lines outside a
-            // quote already short-circuited above, so a blank reaching here means
-            // the scanner is mid-quote and the line is part of the assembled
-            // statement. ECHO=queries echoes only completed queries — handled
-            // separately by the exec path.
-            if (ctx.settings.echo === "all") {
-                ctx.stdout.write(line + "\n");
-            }
-            // 2a. `exit`/`quit` keyword handling.
-            //
-            //   - Empty buffer  → exit the REPL.
-            //   - Non-empty buf → print "Use \\q to quit." hint and continue
-            //     (buffer is preserved so the user can resume editing).
-            //
-            // The buffer may carry whitespace from a prior line's tail, so we
-            // trim before checking.
-            // Bare `quit`/`exit` (and `help` below) are an INTERACTIVE-only
-            // convenience — upstream gates them on `cur_cmd_interactive`. In a
-            // non-interactive script (`printf 'quit;\n' | psql`) they must fall
-            // through and be sent to the server as SQL (syntax error → exit 3),
-            // not silently exit 0.
-            if (!ctx.settings.notty && isQuitKeyword(line)) {
-                if (queryBuf.trim().length === 0) {
-                    reader.pushHistory(line);
-                    exitRequested = true;
-                    break;
-                }
-                ctx.stdout.write("Use \\q to quit.\n");
-                continue;
-            }
-            // 2b. `help` keyword handling, same shape.
-            //
-            //   - Empty buffer  → print the help text, continue.
-            //   - Non-empty buf → print "Use \\? for help." hint, continue.
-            if (!ctx.settings.notty && isHelpKeyword(line)) {
-                if (queryBuf.trim().length === 0) {
-                    reader.pushHistory(line);
-                    ctx.stdout.write(HELP_TEXT);
-                }
-                else {
-                    ctx.stdout.write("Use \\? for help.\n");
-                }
-                continue;
-            }
-            // 3. Push to history once we have a complete submitted line (only
-            //    when there's something non-blank to record).
-            reader.pushHistory(line);
-            await processChunk(line + "\n");
-        }
-        // EOF: if there's a residual non-empty buffer in non-interactive mode,
-        // dispatch it (mirroring upstream's tail-of-MainLoop block). For
-        // interactive mode upstream skips this; we match the behaviour. We also
-        // require the buffer to contain non-whitespace SQL — trailing blanks
-        // between statement boundaries and EOF should not produce an empty
-        // execSimple call.
-        if (!exitRequested &&
-            queryBuf.trim().length > 0 &&
-            ctx.settings.notty &&
-            successResult === EXIT_SUCCESS) {
-            if (ctx.cond.isActive()) {
-                sigintState.inQuery = true;
-                const ok = await dispatchSendQuery(ctx, queryBuf);
-                sigintState.inQuery = false;
-                if (ctx.settings.db?.isClosed()) {
-                    ctx.stderr.write("psql: error: connection to server was lost\n");
-                    successResult = EXIT_BADCONN;
-                }
-                else if (!ok && ctx.settings.onErrorStop) {
-                    successResult = EXIT_USER;
-                }
-            }
-            queryBuf = "";
-        }
-        // Warn about unbalanced \if blocks (psql's tail-of-MainLoop check).
-        if (!exitRequested && ctx.cond.depth() > 0) {
-            writeError(ctx, "reached EOF without finding closing \\endif(s)");
-            if (ctx.settings.onErrorStop && ctx.settings.notty) {
-                successResult = EXIT_USER;
-            }
-        }
-        // NOTE: we deliberately do NOT escalate to EXIT_USER just because the last
-        // statement errored. Real psql exits 0 from piped stdin / `-f` even when a
-        // statement failed, UNLESS ON_ERROR_STOP is set — and that case is already
-        // handled by the per-statement `successResult = EXIT_USER` paths above
-        // (verified on psql 18.4: `printf 'SELECT 1;\nSELECT 1/0;\n' | psql` → 0).
-    }
-    finally {
-        await reader.close();
-        removeSigint();
-        if (removeNotificationHandler)
-            removeNotificationHandler();
-        if (removeNoticeHandler)
-            removeNoticeHandler();
-    }
-    return successResult;
+const runMainLoop = async (ctx) => {
+	let queryBuf = "";
+	const reader = await makeLineReader(ctx, { getQueryBuf: () => queryBuf });
+	let scanState = initialScanState();
+	let stmtLineNumber = 1;
+	let successResult = 0;
+	let exitRequested = false;
+	const condScanStateStack = [];
+	const resetBuf = () => {
+		queryBuf = "";
+		scanState = initialScanState();
+		stmtLineNumber = 1;
+	};
+	const checkConnectionLost = () => {
+		if (ctx.settings.db?.isClosed()) {
+			ctx.stderr.write("psql: error: connection to server was lost\n");
+			successResult = 2;
+			exitRequested = true;
+			return true;
+		}
+		return false;
+	};
+	const sigintState = {
+		inQuery: false,
+		resetBuf
+	};
+	const removeSigint = installSigint(ctx, sigintState);
+	refreshConnectionVars(ctx);
+	const removeNotificationHandler = installNotificationHandler(ctx, reader);
+	const removeNoticeHandler = installNoticeHandler(ctx, reader);
+	const computePrompt = (status) => {
+		if (ctx.settings.notty) return "";
+		const name = queryBuf.trim().length === 0 || status === "ready" ? "PROMPT1" : status === "copy" ? "PROMPT3" : "PROMPT2";
+		const promptCtx = buildPromptContext(ctx, status, stmtLineNumber);
+		return renderPromptByName(name, promptCtx);
+	};
+	const sqlVarLookup = (name) => ctx.settings.vars.get(name);
+	const slashCmdMode = (cmdName) => {
+		const spec = ctx.registry.lookup(cmdName);
+		if (!spec) return void 0;
+		if (spec.argMode === "whole-line") return "whole-line";
+		if (cmdName === "w" || cmdName === "o") return "filepipe";
+	};
+	/**
+	* Strip block / line comments cheaply before scanning so a COPY-shaped
+	* comment doesn't trigger pre-buffering or sink wiring.
+	*/
+	const stripSqlComments = (sql) => sql.replace(/\/\*[\s\S]*?\*\//g, "").replace(/--[^\n]*/g, "");
+	/**
+	* Count the number of `COPY ... FROM STDIN` segments in `sql`. Upstream
+	* `handleCopyIn` in copy.c is invoked for each one that hits the wire as
+	* a `\;`-chained simple-query batch; the mainloop must pre-buffer the
+	* `\.`-terminated data block per occurrence and hand them to the wire
+	* layer before dispatch so CopyInResponse is satisfied without a
+	* blocking callback into the REPL.
+	*
+	* The regex tolerates the optional column list (`COPY t (a, b)`) and the
+	* format clause (`COPY t FROM STDIN WITH (...)` / `... CSV ...`). False
+	* positives inside string literals / comments are possible but extremely
+	* rare in scripted workloads — and a false positive only over-consumes
+	* lines from the input, which is recoverable. The conservative regex
+	* here matches upstream `psql`'s scanner heuristics closely enough for
+	* the conformance suite (`psql.sql` lines around 1467-1476).
+	*/
+	const countCopyFromStdin = (sql) => {
+		const stripped = stripSqlComments(sql);
+		const re = /\bCOPY\b[\s\S]*?\bFROM\s+STDIN\b/giu;
+		let n = 0;
+		while (re.exec(stripped) !== null) n += 1;
+		return n;
+	};
+	/**
+	* `true` when `sql` contains at least one `COPY ... TO STDOUT` segment.
+	* The wire layer routes mid-batch CopyData into our `copyOutMidBatchSink`
+	* when it's set; we install one for the duration of a batch that mentions
+	* `TO STDOUT` so the bytes land on the active output stream.
+	*/
+	const hasCopyToStdout = (sql) => /\bCOPY\b[\s\S]*?\bTO\s+STDOUT\b/iu.test(stripSqlComments(sql));
+	/**
+	* Read one COPY-FROM-STDIN data block: consume lines from the reader
+	* until a bare `\.` arrives (or EOF / null). Returns the concatenated
+	* payload as a Buffer with trailing newlines preserved (the wire side
+	* sends the bytes verbatim; the server treats them as the COPY input).
+	* The `\.` terminator itself is NOT included.
+	*/
+	const readCopyDataBlock = async () => {
+		const lines = [];
+		for (;;) {
+			const line = await reader.readLine("");
+			if (line === null) break;
+			if (line.replace(/\s+$/, "") === "\\.") break;
+			lines.push(line);
+		}
+		const text = lines.length === 0 ? "" : lines.join("\n") + "\n";
+		return Buffer.from(text, "utf8");
+	};
+	/**
+	* Process the assembled queryBuf+line through scanSql, dispatching the
+	* boundaries it finds. Returns when we hit `incomplete`/`eof` and need
+	* the next input line.
+	*/
+	const processChunk = async (chunk) => {
+		let working = chunk;
+		while (working.length > 0) {
+			const result = scanSql(working, scanState, sqlVarLookup, slashCmdMode, { singleline: ctx.settings.singleline });
+			scanState = result.nextState;
+			if (result.kind === "semicolon") {
+				const sqlText = queryBuf + result.sql;
+				queryBuf = "";
+				working = working.slice(result.consumed);
+				scanState = initialScanState();
+				stmtLineNumber = 1;
+				if (!ctx.cond.isActive()) continue;
+				const copyCount = ctx.settings.db ? countCopyFromStdin(sqlText) : 0;
+				const wantsCopyOut = ctx.settings.db !== void 0 && hasCopyToStdout(sqlText);
+				if (copyCount > 0 && ctx.settings.db) {
+					const conn = ctx.settings.db;
+					if (typeof conn.queueCopyInData === "function") {
+						conn.clearCopyInDataQueue?.();
+						for (let i = 0; i < copyCount; i += 1) {
+							const block = await readCopyDataBlock();
+							conn.queueCopyInData(block);
+						}
+					}
+				}
+				if (wantsCopyOut && ctx.settings.db) {
+					const conn = ctx.settings.db;
+					const out = pickOut(ctx);
+					conn.copyOutMidBatchSink = (chunk) => {
+						out.write(chunk);
+					};
+				}
+				sigintState.inQuery = true;
+				const ok = await dispatchSendQuery(ctx, sqlText);
+				sigintState.inQuery = false;
+				if (copyCount > 0 && ctx.settings.db) ctx.settings.db.clearCopyInDataQueue?.();
+				if (wantsCopyOut && ctx.settings.db) {
+					const conn = ctx.settings.db;
+					conn.copyOutMidBatchSink = null;
+				}
+				if (checkConnectionLost()) return;
+				if (!ok && ctx.settings.onErrorStop) {
+					successResult = 3;
+					exitRequested = true;
+					return;
+				}
+				continue;
+			}
+			if (result.kind === "backslash") {
+				const slashOnlyLine = result.sql.length === 0 && queryBuf.length === 0;
+				queryBuf += result.sql;
+				working = working.slice(result.consumed);
+				const cmdName = result.cmd;
+				if (COND_COMMAND_NAMES.has(cmdName)) {
+					const scanStateBefore = { ...scanState };
+					const r = await dispatchCondCommand(ctx, cmdName, result.rest, queryBuf);
+					if (r.handled && r.result?.status === "exit") {
+						exitRequested = true;
+						return;
+					}
+					if (r.handled && r.result?.truncateBufTo !== void 0) {
+						const target = r.result.truncateBufTo;
+						if (target < queryBuf.length) queryBuf = queryBuf.slice(0, target);
+						const savedScan = condScanStateStack[condScanStateStack.length - 1];
+						if (savedScan !== void 0) scanState = { ...savedScan };
+					}
+					if (cmdName === "if") condScanStateStack.push(scanStateBefore);
+					else if (cmdName === "elif" || cmdName === "else") {
+						if (condScanStateStack.length > 0 && r.result?.status === "ok") condScanStateStack[condScanStateStack.length - 1] = { ...scanState };
+					} else if (cmdName === "endif") {
+						if (r.result?.status === "ok") condScanStateStack.pop();
+					}
+					if (r.handled && r.result?.status === "error" && ctx.settings.onErrorStop) {
+						successResult = 3;
+						exitRequested = true;
+						return;
+					}
+					continue;
+				}
+				if (!ctx.cond.isActive()) {
+					if (ctx.registry.lookup(cmdName) === void 0) ctx.stderr.write(`invalid command \\${cmdName}\n`);
+					continue;
+				}
+				const bres = await dispatchRegisteredCommand(ctx, cmdName, result.rest, queryBuf);
+				if (bres?.status === "exit") {
+					exitRequested = true;
+					return;
+				}
+				if (bres?.status === "reset-buf") {
+					queryBuf = bres.newBuf ?? "";
+					scanState = initialScanState();
+					stmtLineNumber = 1;
+					if (working.startsWith("\r\n")) working = working.slice(2);
+					else if (working.startsWith("\n") || working.startsWith("\r")) working = working.slice(1);
+				}
+				if (bres?.status !== "reset-buf" && slashOnlyLine) {
+					if (working.startsWith("\r\n")) working = working.slice(2);
+					else if (working.startsWith("\n") || working.startsWith("\r")) working = working.slice(1);
+				}
+				if (bres?.status === "error") {
+					queryBuf = "";
+					scanState = initialScanState();
+					stmtLineNumber = 1;
+					if (working.startsWith("\r\n")) working = working.slice(2);
+					else if (working.startsWith("\n") || working.startsWith("\r")) working = working.slice(1);
+					else {
+						const nlIdx = working.indexOf("\n");
+						working = nlIdx === -1 ? "" : working.slice(nlIdx + 1);
+					}
+				}
+				if (checkConnectionLost()) return;
+				if (bres?.status === "error" && ctx.settings.onErrorStop) {
+					successResult = 3;
+					exitRequested = true;
+					return;
+				}
+				continue;
+			}
+			queryBuf += result.sql;
+			working = "";
+			return;
+		}
+	};
+	try {
+		while (!exitRequested) {
+			const prompt = computePrompt(queryBuf.trim().length === 0 ? "ready" : scanState.promptStatus === "ready" ? "continue" : scanState.promptStatus);
+			const queued = consumeNext();
+			if (queued !== null) {
+				await processChunk(queued.endsWith("\n") ? queued : queued + "\n");
+				continue;
+			}
+			let line;
+			try {
+				line = await reader.readLine(prompt);
+			} catch (err) {
+				if (err.name === "SignalError") {
+					resetBuf();
+					continue;
+				}
+				throw err;
+			}
+			if (line === null) break;
+			const scanInQuote = scanState.inBlockComment > 0 || scanState.inSingleQuote || scanState.inDoubleQuote || scanState.dollarTag !== null;
+			if (line.length === 0 && !scanInQuote) continue;
+			if (ctx.settings.echo === "all") ctx.stdout.write(line + "\n");
+			if (!ctx.settings.notty && isQuitKeyword(line)) {
+				if (queryBuf.trim().length === 0) {
+					reader.pushHistory(line);
+					exitRequested = true;
+					break;
+				}
+				ctx.stdout.write("Use \\q to quit.\n");
+				continue;
+			}
+			if (!ctx.settings.notty && isHelpKeyword(line)) {
+				if (queryBuf.trim().length === 0) {
+					reader.pushHistory(line);
+					ctx.stdout.write(HELP_TEXT);
+				} else ctx.stdout.write("Use \\? for help.\n");
+				continue;
+			}
+			reader.pushHistory(line);
+			await processChunk(line + "\n");
+		}
+		if (!exitRequested && queryBuf.trim().length > 0 && ctx.settings.notty && successResult === 0) {
+			if (ctx.cond.isActive()) {
+				sigintState.inQuery = true;
+				const ok = await dispatchSendQuery(ctx, queryBuf);
+				sigintState.inQuery = false;
+				if (ctx.settings.db?.isClosed()) {
+					ctx.stderr.write("psql: error: connection to server was lost\n");
+					successResult = 2;
+				} else if (!ok && ctx.settings.onErrorStop) successResult = 3;
+			}
+			queryBuf = "";
+		}
+		if (!exitRequested && ctx.cond.depth() > 0) {
+			writeError(ctx, "reached EOF without finding closing \\endif(s)");
+			if (ctx.settings.onErrorStop && ctx.settings.notty) successResult = 3;
+		}
+	} finally {
+		await reader.close();
+		removeSigint();
+		if (removeNotificationHandler) removeNotificationHandler();
+		if (removeNoticeHandler) removeNoticeHandler();
+	}
+	return successResult;
 };
 /**
- * Test-only surface. Exposes the small VI_MODE helpers so the matching unit
- * tests can exercise the parse / translate logic without engaging the
- * raw-mode LineEditor. Treated as private — callers should not rely on it.
- */
-export const __testing = {
-    parseBoolVar,
-    viModeOption,
+* Test-only surface. Exposes the small VI_MODE helpers so the matching unit
+* tests can exercise the parse / translate logic without engaging the
+* raw-mode LineEditor. Treated as private — callers should not rely on it.
+*/
+const __testing = {
+	parseBoolVar,
+	viModeOption
 };
+//#endregion
+export { EXIT_BADCONN, EXIT_FAILURE, EXIT_SUCCESS, EXIT_USER, __testing, runMainLoop };