neon 3.0.0 → 3.1.1

package/dist/_chunks/cmd_pipeline-CUbBO9U_.js

@@ -0,0 +1,2818 @@
+import { writeErr, writeOut } from "../psql/command/shared.js";
+import { formatDurationMs } from "../psql/print/units.js";
+import { alignedPrinter } from "../psql/print/aligned.js";
+import { asciidocPrinter } from "../psql/print/asciidoc.js";
+import { csvPrinter } from "../psql/print/csv.js";
+import { htmlPrinter } from "../psql/print/html.js";
+import { jsonPrinter } from "../psql/print/json.js";
+import { latexLongtablePrinter, latexPrinter } from "../psql/print/latex.js";
+import { troffMsPrinter } from "../psql/print/troff.js";
+import { unalignedPrinter } from "../psql/print/unaligned.js";
+import { openPager, shouldPage } from "../psql/print/pager.js";
+import { formatErrorReport, psqlErrorPrefix } from "../psql/command/cmd_meta.js";
+import { applyPset } from "../psql/command/cmd_format.js";
+import { closeSync, createWriteStream, fsyncSync, openSync, promises } from "node:fs";
+import * as path from "node:path";
+import { platform } from "node:os";
+import { spawn } from "node:child_process";
+//#region src/psql/core/common.ts
+/**
+* psql common — the unified send-query / process-result pipeline.
+*
+* TypeScript port of selected functions in `src/bin/psql/common.c`:
+*
+*   - {@link sendQuery}        ← `SendQuery`
+*   - {@link executeAndPrint}  ← `ExecQueryAndProcessResults` (the inner
+*                                 result-processing slice, without the
+*                                 AUTOCOMMIT / savepoint scaffolding)
+*   - {@link psqlExec}         ← `PSQLexec`
+*
+* The minimal version of this logic was inlined in `mainloop.ts` after WP-12;
+* this WP extracts and polishes it. The pieces wired in here:
+*
+*   - AUTOCOMMIT: when the variable is 'off' (default 'on') and the current
+*     transaction is idle, prepend `BEGIN` once before the next non-exempt
+*     statement. The set of exempt commands mirrors upstream
+*     `command_no_begin()` — transaction-control verbs and a handful of
+*     non-transactional DDL.
+*
+*   - ON_ERROR_ROLLBACK: 'off' (default) | 'on' | 'interactive'. When active
+*     and we're inside a transaction, issue
+*     `SAVEPOINT pg_psql_temporary_savepoint` before the statement; on error
+*     `ROLLBACK TO`, on success `RELEASE` (unless the statement is itself a
+*     savepoint-management verb that already drops/replaces it).
+*
+*   - FETCH_COUNT: integer; when >0 and the statement is a single SELECT-ish
+*     query, wrap it in `DECLARE _psql_cursor CURSOR FOR ...; FETCH FORWARD
+*     N FROM _psql_cursor` until exhausted. Non-SELECT statements fall back
+*     to the simple path.
+*
+*   - SINGLESTEP: when `settings.singlestep` is true, print the SQL to stderr
+*     with the upstream confirmation banner and read one line from stdin.
+*     Input that starts with 'x' cancels the statement.
+*
+*   - Timing: when `settings.timing` is true, measure wallclock around the
+*     send/print path and write a `Time: X.XXX ms` line to stdout (mirrors
+*     upstream's `printf` in common.c, and matches the existing mainloop
+*     test expectations).
+*
+* What's deliberately not done here:
+*
+*   - SINGLELINE (-S): treating LF as a semicolon is a scanner concern, so it
+*     lives there — `scanSql` honours `ScanOptions.singleline` and the mainloop
+*     passes `settings.singleline` through on each pass. `sendQuery` itself
+*     needs no SINGLELINE branch; by the time a statement reaches here the
+*     scanner has already drawn the boundary.
+*
+*   - Pipeline mode (-X / `\startpipeline`): upstream gates SendQuery on
+*     `pset.send_mode == PSQL_SEND_PIPELINE`; that path is owned by WP-21.
+*
+*   - COPY FROM STDIN / TO STDOUT: upstream's ProcessResult dispatches on
+*     `PGRES_COPY_IN/OUT`. That belongs to WP-16; here we surface a clear
+*     error message if we ever see a copy result come back through
+*     `execSimple`.
+*/
+const readTxStatus = (conn) => {
+	return conn.txStatus ?? "I";
+};
+const SAVEPOINT_NAME = "pg_psql_temporary_savepoint";
+const CURSOR_NAME = "_psql_cursor";
+/**
+* Strip leading whitespace and `--` line / slash-star block comments from
+* `sql`. Mirrors what upstream psql's scanner advances past before handing a
+* statement to `PQexec` — the server-reported error `position` is a 1-based
+* offset into THAT trimmed buffer, so the `LINE N:` re-print computed from
+* `count('\n')` in `sql.slice(0, position - 1)` aligns with vanilla output
+* only when the same leading prelude is stripped here too.
+*
+* Block comments support nested depths (PG extension). Embedded comments
+* mid-statement are intentionally NOT stripped — they participate in the
+* line count of the executing statement, same as upstream.
+*
+* Exported for cmd_io / cmd_pipeline so backslash commands that capture or
+* inspect `queryBuf` see the same shape that the wire and `lastQuery`
+* receive.
+*/
+const stripLeadingCommentsAndWS = (sql) => {
+	let i = 0;
+	const n = sql.length;
+	while (i < n) {
+		const c = sql.charCodeAt(i);
+		if (c === 32 || c === 9 || c === 10 || c === 13 || c === 12 || c === 11) {
+			i++;
+			continue;
+		}
+		if (c === 45 && sql.charCodeAt(i + 1) === 45) {
+			i += 2;
+			while (i < n && sql.charCodeAt(i) !== 10) i++;
+			continue;
+		}
+		if (c === 47 && sql.charCodeAt(i + 1) === 42) {
+			i += 2;
+			let depth = 1;
+			while (i < n && depth > 0) if (sql.charCodeAt(i) === 47 && sql.charCodeAt(i + 1) === 42) {
+				depth++;
+				i += 2;
+			} else if (sql.charCodeAt(i) === 42 && sql.charCodeAt(i + 1) === 47) {
+				depth--;
+				i += 2;
+			} else i++;
+			continue;
+		}
+		break;
+	}
+	return i === 0 ? sql : sql.slice(i);
+};
+/** Strip leading whitespace and SQL comments, then upper-case for matching. */
+const peekKeywords = (sql, count = 3) => {
+	let i = 0;
+	while (i < sql.length) {
+		const ch = sql[i];
+		if (ch === " " || ch === "	" || ch === "\n" || ch === "\r") {
+			i++;
+			continue;
+		}
+		if (ch === "-" && sql[i + 1] === "-") {
+			const nl = sql.indexOf("\n", i + 2);
+			if (nl === -1) return [];
+			i = nl + 1;
+			continue;
+		}
+		if (ch === "/" && sql[i + 1] === "*") {
+			const end = sql.indexOf("*/", i + 2);
+			if (end === -1) return [];
+			i = end + 2;
+			continue;
+		}
+		break;
+	}
+	return sql.slice(i).split(/[\s,;()]+/u, count + 1).slice(0, count).map((w) => w.toUpperCase());
+};
+/** Mirror of `command_no_begin()` in psql/common.c. */
+const commandNoBegin = (sql) => {
+	const [w0, w1, w2, w3] = peekKeywords(sql, 4);
+	if (!w0) return false;
+	switch (w0) {
+		case "ABORT":
+		case "BEGIN":
+		case "COMMIT":
+		case "END":
+		case "ROLLBACK":
+		case "START":
+		case "SAVEPOINT":
+		case "RELEASE": return true;
+		case "PREPARE": return w1 === "TRANSACTION";
+		case "VACUUM": return true;
+		case "CLUSTER": return w1 === void 0 || w1 === "";
+		case "CREATE":
+			if (w1 === "DATABASE" || w1 === "TABLESPACE") return true;
+			if (w1 === "INDEX" && w2 === "CONCURRENTLY") return true;
+			if (w1 === "UNIQUE" && w2 === "INDEX" && w3 === "CONCURRENTLY") return true;
+			return false;
+		case "DROP":
+			if (w1 === "DATABASE" || w1 === "TABLESPACE") return true;
+			if (w1 === "INDEX" && w2 === "CONCURRENTLY") return true;
+			return false;
+		case "REINDEX":
+			if (w1 === "DATABASE" || w1 === "SYSTEM") return true;
+			if (w1 === "INDEX" && w2 === "CONCURRENTLY") return true;
+			if (w1 === "TABLE" && w2 === "CONCURRENTLY") return true;
+			return false;
+		case "ALTER": return w1 === "SYSTEM";
+		case "DISCARD": return w1 === "ALL";
+		default: return false;
+	}
+};
+/** True when the statement opens with SELECT / VALUES / TABLE / WITH. */
+const isSelectCommand = (sql) => {
+	const [w0] = peekKeywords(sql, 1);
+	return w0 === "SELECT" || w0 === "VALUES" || w0 === "TABLE" || w0 === "WITH";
+};
+/**
+* Does this statement effectively destroy / replace the temporary savepoint?
+* Upstream's `svpt_gone` flag is set when the user's command is one of
+* COMMIT / ROLLBACK / SAVEPOINT / RELEASE. In those cases we must skip the
+* matching RELEASE because the named savepoint no longer exists.
+*/
+const destroysSavepoint = (sql) => {
+	const [w0] = peekKeywords(sql, 1);
+	return w0 === "COMMIT" || w0 === "ROLLBACK" || w0 === "SAVEPOINT" || w0 === "RELEASE";
+};
+const pickPrinter = (settings) => {
+	switch (settings.popt.topt.format) {
+		case "aligned":
+		case "wrapped": return alignedPrinter;
+		case "unaligned": return unalignedPrinter;
+		case "csv": return csvPrinter;
+		case "json": return jsonPrinter;
+		case "html": return htmlPrinter;
+		case "asciidoc": return asciidocPrinter;
+		case "latex": return latexPrinter;
+		case "latex-longtable": return latexLongtablePrinter;
+		case "troff-ms": return troffMsPrinter;
+		default: return alignedPrinter;
+	}
+};
+/**
+* Pick the output target for a query result.
+*
+* Precedence: explicit `oneShot` argument > the settings stash from
+* `\o FILE` (WP-15) > the REPL context's `stdout`.
+*/
+const pickOut$1 = (ctx, oneShot) => {
+	if (oneShot) return oneShot;
+	return getQueryFout(ctx.settings) ?? ctx.stdout;
+};
+const readAutocommit = (settings) => settings.vars.asBool("AUTOCOMMIT", true);
+const readOnErrorRollback = (settings) => {
+	const raw = settings.vars.get("ON_ERROR_ROLLBACK");
+	if (raw === void 0) return settings.onErrorRollback;
+	const v = raw.toLowerCase();
+	if (v === "interactive") return "interactive";
+	if (v === "on" || v === "true" || v === "yes" || v === "1") return "on";
+	return "off";
+};
+const readFetchCount = (settings) => {
+	const v = settings.vars.asInt("FETCH_COUNT", settings.fetchCount);
+	if (typeof v !== "number") return 0;
+	return Math.max(0, v | 0);
+};
+const readSinglestep = (settings) => settings.singlestep || settings.vars.asBool("SINGLESTEP", false);
+/**
+* SHOW_ALL_RESULTS controls multi-statement `\;` printing. Default 'on' —
+* every result set is rendered. When 'off' / '0', only the LAST result set
+* is printed (upstream's `pset.show_all_results` flag, consulted by
+* `PrintQueryResults` in common.c).
+*/
+const readShowAllResults = (settings) => settings.vars.asBool("SHOW_ALL_RESULTS", true);
+const writeError = (ctx, message) => {
+	ctx.stderr.write(`psql: ERROR:  ${message}\n`);
+};
+/**
+* Render the verbosity-aware error report for the most recently captured
+* query error and write it to `ctx.stderr`. The leading severity line gets
+* the same `psql:[<file>:<n>]:` diagnostic prefix that upstream's
+* `pg_log_pre_callback` prepends — matching the format the regression-
+* derived conformance suite expects (e.g. `psql:<stdin>:N: ERROR: ...`).
+* Subsequent layers (`LINE N: ...`, caret, `DETAIL: ...`, ...) follow on
+* their own lines per {@link formatErrorReport}, unprefixed, to match
+* libpq's `PQresultErrorMessage` output shape. When the captured error is
+* missing (defensive — callers should always pair this with a preceding
+* `recordError`) we fall back to the plain client-side {@link writeError}
+* form so we never swallow the message entirely.
+*
+* Exported so the bind-path in mainloop can share the renderer.
+*/
+const writeQueryError = (ctx, fallbackMessage) => {
+	const e = ctx.settings.lastErrorResult;
+	if (!e || !e.message && !e.code && !e.sqlstate) {
+		writeError(ctx, fallbackMessage);
+		return;
+	}
+	const lines = formatErrorReport(e, ctx.settings.verbosity, ctx.settings.showContext);
+	const prefixed = [psqlErrorPrefix(ctx.settings) + lines[0], ...lines.slice(1)];
+	ctx.stderr.write(prefixed.join("\n") + "\n");
+};
+/**
+* Strip leading whitespace from a query and rebase a 1-based server position
+* to match. Mirrors upstream psql/mainloop.c's behaviour: a line containing
+* only a backslash command does not leave a `\n` in the query buffer, so the
+* subsequent SQL statement starts at "line 1" of its own context rather than
+* inheriting a blank line. Our mainloop doesn't perform that strip, so the
+* captured `sqlText` sometimes has a leading `\n` (e.g. after `\set
+* FETCH_COUNT 1\nSELECT error;`). Without this normalisation, `\errverbose`
+* would render `LINE 2: SELECT error;` where upstream renders `LINE 1: …`.
+*
+* Returns the trimmed text and the rebased position. If the rebased
+* position would land outside the trimmed text, it is dropped so the
+* formatter skips the `LINE`/caret block instead of mis-pointing.
+*/
+const normaliseSqlAndPosition = (sqlText, position) => {
+	let leading = 0;
+	while (leading < sqlText.length) {
+		const ch = sqlText.charCodeAt(leading);
+		if (ch !== 32 && ch !== 9 && ch !== 10 && ch !== 13 && ch !== 12) break;
+		leading++;
+	}
+	if (leading === 0) return {
+		sqlText,
+		position
+	};
+	const trimmed = sqlText.slice(leading);
+	if (typeof position !== "string") return {
+		sqlText: trimmed,
+		position
+	};
+	const original = parseInt(position, 10);
+	if (!Number.isFinite(original) || original <= 0) return {
+		sqlText: trimmed,
+		position
+	};
+	const rebased = original - leading;
+	if (rebased <= 0 || rebased > trimmed.length) return {
+		sqlText: trimmed,
+		position: void 0
+	};
+	return {
+		sqlText: trimmed,
+		position: String(rebased)
+	};
+};
+/**
+* Capture the full ErrorResponse-shaped payload from a thrown error.
+*
+* Our wire layer copies every named field of the server's ErrorResponse
+* (severity / code / detail / hint / position / file / line / routine /
+* …) onto the thrown Error as own properties (see `asThrowable` in
+* `wire/connection.ts`). We mirror those onto `settings.lastErrorResult`
+* so `\errverbose` can re-render the error in VERBOSE form — including
+* the `LINE N: …` re-print + `^` pointer and the `LOCATION:` footer.
+*
+* `sqlText` is the originating SQL text from the caller; required so the
+* `^` pointer can be positioned under the failing character. Leading
+* whitespace is stripped (and `position` is rebased) so the `LINE N`
+* counter reflects offsets within the user's statement rather than any
+* buffer noise carried over from prior backslash commands.
+*/
+const captureLastError = (settings, err, sqlText) => {
+	const fallbackMessage = err instanceof Error ? err.message : String(err);
+	const e = err ?? {};
+	const code = e.code;
+	const normalised = normaliseSqlAndPosition(sqlText, e.position);
+	settings.lastErrorResult = {
+		severity: e.severity,
+		code,
+		sqlstate: code,
+		message: e.message ?? fallbackMessage,
+		detail: e.detail,
+		hint: e.hint,
+		position: normalised.position,
+		internalPosition: e.internalPosition,
+		internalQuery: e.internalQuery,
+		where: e.where,
+		schema: e.schema,
+		table: e.table,
+		column: e.column,
+		dataType: e.dataType,
+		constraint: e.constraint,
+		file: e.file,
+		line: e.line,
+		routine: e.routine,
+		sqlText: normalised.sqlText
+	};
+	return settings.lastErrorResult.message ?? fallbackMessage;
+};
+const recordError = (ctx, err, sqlText = "") => captureLastError(ctx.settings, err, sqlText);
+/**
+* Update the per-statement diagnostic psql variables that upstream's
+* `SetResultVariables` / `SetErrorVariables` in `src/bin/psql/common.c`
+* maintains. Called after every dispatched statement (success and error
+* paths) so `\echo :LAST_ERROR_MESSAGE` and friends produce the same
+* values vanilla psql does.
+*
+*   - `SQLSTATE`         SQLSTATE of the *most recent* statement —
+*                        `"00000"` on success, the server-reported code
+*                        on error (defaults to `"XX000"` when missing).
+*   - `ERROR`            `"true"` if the most recent statement failed,
+*                        else `"false"`.
+*   - `ROW_COUNT`        affected/returned row count of the most recent
+*                        statement (from libpq's `PQcmdTuples`). `"0"`
+*                        on error.
+*   - `LAST_ERROR_*`     sticky — only mutated on error. Mirrors
+*                        upstream's "preserve until the next failure"
+*                        contract so a successful statement does not
+*                        clobber the prior error info.
+*
+* Exported so mainloop's bind / pipeline paths (which bypass {@link
+* sendQuery}) can share the same updater.
+*/
+const refreshErrorVars = (settings, outcome) => {
+	const { vars } = settings;
+	if (outcome.kind === "error") {
+		const last = settings.lastErrorResult;
+		const code = last?.code ?? last?.sqlstate ?? "XX000";
+		const message = last?.message ?? "";
+		vars.set("LAST_ERROR_MESSAGE", message);
+		vars.set("LAST_ERROR_SQLSTATE", code);
+		vars.set("SQLSTATE", code);
+		vars.set("ERROR", "true");
+		vars.set("ROW_COUNT", "0");
+		return;
+	}
+	vars.set("SQLSTATE", "00000");
+	vars.set("ERROR", "false");
+	const rc = outcome.rowCount ?? 0;
+	vars.set("ROW_COUNT", String(rc));
+};
+const readOneLine = (stdin) => new Promise((resolve) => {
+	let buf = "";
+	let resolved = false;
+	const onData = (chunk) => {
+		buf += chunk.toString();
+		const nl = buf.indexOf("\n");
+		if (nl !== -1) {
+			const line = buf.slice(0, nl);
+			cleanup();
+			if (!resolved) {
+				resolved = true;
+				resolve(line);
+			}
+		}
+	};
+	const onEnd = () => {
+		cleanup();
+		if (!resolved) {
+			resolved = true;
+			resolve(buf);
+		}
+	};
+	const cleanup = () => {
+		stdin.off("data", onData);
+		stdin.off("end", onEnd);
+		stdin.off("close", onEnd);
+	};
+	stdin.on("data", onData);
+	stdin.once("end", onEnd);
+	stdin.once("close", onEnd);
+});
+const confirmSinglestep = async (ctx, sql) => {
+	ctx.stderr.write(`***(Single step mode: verify command)*******************************************\n${sql}\n***(press return to proceed or enter x and return to cancel)********************\n`);
+	return !(await readOneLine(ctx.stdin)).trim().toLowerCase().startsWith("x");
+};
+/**
+* Reconstruct the libpq-style CommandComplete tag from the parsed parts our
+* wire layer stores on a ResultSet. INSERT carries `oid` + `rowCount`; the
+* other DML verbs (UPDATE/DELETE/MERGE/SELECT/MOVE/FETCH/COPY) carry just a
+* `rowCount`; DDL has neither.
+*
+* Matches upstream psql's `PQcmdStatus(conn)` output (which is the raw tag
+* the server sent — we round-trip it through our parser).
+*/
+const formatCommandTag = (rs) => {
+	const command = (rs.command || "").trim();
+	if (command.length === 0) return "";
+	if (command === "INSERT") return `INSERT ${rs.oid ?? 0} ${rs.rowCount ?? 0}`;
+	if (rs.rowCount !== null && rs.rowCount !== void 0) return `${command} ${rs.rowCount}`;
+	return command;
+};
+/**
+* Decide whether the pager should activate for the given batch of result
+* sets. We page when ANY of the sets-that-will-be-printed (i.e. tuples-
+* producing, and not gated out by SHOW_ALL_RESULTS) crosses the threshold.
+* The decision is centralised here so callers can override individual
+* decision inputs (e.g. tests that inject a fake `output`).
+*/
+const pickPagerDecision = (ctx, results, out) => {
+	const popt = ctx.settings.popt.topt;
+	if (popt.pager === "off") return false;
+	const redirectedOutput = getQueryFout(ctx.settings) !== null;
+	if (redirectedOutput) return false;
+	const showAll = readShowAllResults(ctx.settings);
+	const lastIdx = results.length - 1;
+	for (let i = 0; i < results.length; i++) {
+		const rs = results[i];
+		if (rs.fields.length === 0) continue;
+		if (!(showAll || i === lastIdx)) continue;
+		if (shouldPage({
+			pager: popt.pager,
+			pagerMinLines: popt.pagerMinLines,
+			rowCount: rs.rows.length,
+			colCount: rs.fields.length,
+			output: out,
+			redirectedOutput
+		})) return true;
+	}
+	return false;
+};
+const renderResultSets = async (ctx, results, out) => {
+	const printer = pickPrinter(ctx.settings);
+	let rowsAffected = 0;
+	let rowsPrinted = 0;
+	const showAll = readShowAllResults(ctx.settings);
+	const lastIdx = results.length - 1;
+	const tuplesOnly = ctx.settings.popt.topt.tuplesOnly;
+	const pager = pickPagerDecision(ctx, results, out) ? openPager({
+		pager: ctx.settings.popt.topt.pager,
+		pagerMinLines: ctx.settings.popt.topt.pagerMinLines,
+		stdout: out
+	}) : null;
+	const sink = pager?.spawned ? pager.out : out;
+	try {
+		for (let i = 0; i < results.length; i++) {
+			const rs = results[i];
+			const shouldEmit = showAll || i === lastIdx;
+			if (rs.copyOutBytes && rs.copyOutBytes.length > 0) for (const chunk of rs.copyOutBytes) sink.write(chunk);
+			if (rs.fields.length === 0) {
+				if (shouldEmit && !tuplesOnly && !ctx.settings.quiet && !rs.copyOutBytes) {
+					const tag = formatCommandTag(rs);
+					if (tag.length > 0) sink.write(`${tag}\n`);
+				}
+				rowsAffected += rs.rowCount ?? 0;
+			} else {
+				if (shouldEmit) await printer.printQuery(rs, ctx.settings.popt, sink);
+				rowsPrinted += rs.rows.length;
+			}
+		}
+	} finally {
+		if (pager?.spawned) try {
+			await pager.close();
+		} catch {}
+	}
+	const lastRowCount = results.length === 0 ? null : (() => {
+		const rs = results[results.length - 1];
+		if (rs.fields.length > 0) return rs.rows.length;
+		return rs.rowCount ?? null;
+	})();
+	return {
+		rowsAffected,
+		rowsPrinted,
+		lastRowCount
+	};
+};
+/**
+* Render a single {@link ResultSet} through the active printer and the
+* configured output target (respecting `\o FILE` redirects). Used by the
+* `\bind` / extended-query path in {@link mainloop.dispatchSendQuery} which
+* comes back with a single result instead of the array shape `execSimple`
+* produces. Returns a tally consistent with {@link renderResultSets}.
+*/
+const renderResultSet = (ctx, rs, out) => {
+	return renderResultSets(ctx, [rs], out ?? pickOut$1(ctx));
+};
+/**
+* Re-base a server-side `position` field so it points into the user's
+* original SQL rather than the synthetic statement we actually sent.
+*
+* The FETCH_COUNT path sends `DECLARE _psql_cursor NO SCROLL CURSOR FOR
+* <userSql>` for the DECLARE leg and `FETCH FORWARD N FROM _psql_cursor`
+* for each fetch. Server error positions (`P` field) come back in the
+* coordinates of whatever query we sent:
+*
+*   - DECLARE-time parser/planner errors carry a position into the DECLARE
+*     statement. We subtract the length of the prefix (`DECLARE … FOR `)
+*     so the caret lands under the failing token in `userSql`.
+*
+*   - FETCH-time runtime errors come from executing the cursor's underlying
+*     query (which IS `userSql`). The server reports the position relative
+*     to that underlying query, so it's already in `userSql` coordinates
+*     and we leave it alone.
+*
+* If we can't rebase a DECLARE-coord position into `userSql` bounds, we
+* strip it rather than render a caret pointing past end-of-line.
+*/
+const rebasePositionForCursor = (err, wrapper, userSql) => {
+	if (!err || typeof err !== "object") return;
+	const e = err;
+	if (typeof e.position !== "string") return;
+	const original = parseInt(e.position, 10);
+	if (!Number.isFinite(original) || original <= 0) return;
+	const stripped = userSql.replace(/;\s*$/u, "");
+	const offset = wrapper.indexOf(stripped);
+	if (offset === -1) return;
+	const rebased = original - offset;
+	if (rebased <= 0 || rebased > userSql.length) {
+		delete e.position;
+		return;
+	}
+	e.position = String(rebased);
+};
+const runCursorLoop = async (ctx, sql, fetchCount, out) => {
+	if (!ctx.settings.db) throw new Error("no connection to the server");
+	const db = ctx.settings.db;
+	const initiallyIdle = readTxStatus(db) === "I";
+	if (initiallyIdle) await db.execSimple("BEGIN");
+	const stripped = sql.replace(/;\s*$/u, "");
+	const declared = `DECLARE ${CURSOR_NAME} NO SCROLL CURSOR FOR ${stripped}`;
+	const fetchSql = `FETCH FORWARD ${String(fetchCount)} FROM ${CURSOR_NAME}`;
+	const rowsAffected = 0;
+	let rowsPrinted = 0;
+	let cursorOpen = false;
+	let currentWrapper = declared;
+	const printer = pickPrinter(ctx.settings);
+	let merged = null;
+	try {
+		await db.execSimple(declared);
+		cursorOpen = true;
+		while (true) {
+			currentWrapper = fetchSql;
+			const sets = await db.execSimple(fetchSql);
+			if (sets.length === 0) break;
+			const rs = sets[sets.length - 1];
+			const chunkRows = rs.rows.length;
+			if (chunkRows === 0) break;
+			if (merged === null) merged = {
+				command: rs.command,
+				fields: rs.fields,
+				rows: rs.rows.slice(),
+				rowCount: rs.rowCount,
+				oid: rs.oid,
+				notices: rs.notices
+			};
+			else for (const row of rs.rows) merged.rows.push(row);
+			rowsPrinted += chunkRows;
+			if (chunkRows < fetchCount) break;
+		}
+		if (merged !== null) {
+			merged.rowCount = merged.rows.length;
+			await printer.printQuery(merged, ctx.settings.popt, out);
+		}
+		await db.execSimple(`CLOSE ${CURSOR_NAME}`);
+		cursorOpen = false;
+		if (initiallyIdle) await db.execSimple("COMMIT");
+		return {
+			rowsAffected,
+			rowsPrinted,
+			lastRowCount: rowsPrinted
+		};
+	} catch (err) {
+		if (merged !== null) {
+			merged.rowCount = merged.rows.length;
+			const partialOpts = {
+				...ctx.settings.popt,
+				topt: {
+					...ctx.settings.popt.topt,
+					defaultFooter: false,
+					stopTable: false
+				}
+			};
+			try {
+				await printer.printQuery(merged, partialOpts, out);
+			} catch {}
+		}
+		rebasePositionForCursor(err, currentWrapper, sql);
+		if (cursorOpen) try {
+			await db.execSimple(`CLOSE ${CURSOR_NAME}`);
+		} catch {}
+		if (initiallyIdle) try {
+			await db.execSimple("ROLLBACK");
+		} catch {}
+		throw err;
+	}
+};
+const executeAndPrint = async (ctx, sqlRaw, opts = {}) => {
+	const sql = stripLeadingCommentsAndWS(sqlRaw);
+	const started = ctx.settings.timing ? performance.now() : 0;
+	const stats = {
+		rowsAffected: 0,
+		rowsPrinted: 0,
+		fetched: false,
+		hadError: false,
+		durationMs: 0
+	};
+	if (!ctx.settings.db) {
+		writeError(ctx, "no connection to the server");
+		stats.hadError = true;
+		return stats;
+	}
+	const out = pickOut$1(ctx, opts.oneShotOut);
+	const fetchCount = readFetchCount(ctx.settings);
+	let lastRowCount = null;
+	try {
+		if (fetchCount > 0 && isSelectCommand(sql)) {
+			const r = await runCursorLoop(ctx, sql, fetchCount, out);
+			stats.rowsAffected = r.rowsAffected;
+			stats.rowsPrinted = r.rowsPrinted;
+			stats.fetched = true;
+			lastRowCount = r.lastRowCount;
+		} else {
+			const results = await ctx.settings.db.execSimple(sql);
+			const r = await renderResultSets(ctx, results, out);
+			stats.rowsAffected = r.rowsAffected;
+			stats.rowsPrinted = r.rowsPrinted;
+			lastRowCount = r.lastRowCount;
+		}
+	} catch (err) {
+		const partial = err.partialResults;
+		if (partial && partial.length > 0) try {
+			const r = await renderResultSets(ctx, partial, out);
+			stats.rowsAffected = r.rowsAffected;
+			stats.rowsPrinted = r.rowsPrinted;
+		} catch {}
+		const message = recordError(ctx, err, sql);
+		writeQueryError(ctx, message);
+		stats.hadError = true;
+	} finally {
+		if (ctx.settings.timing) {
+			stats.durationMs = performance.now() - started;
+			ctx.stdout.write("\n" + formatDurationMs(stats.durationMs) + "\n");
+		}
+	}
+	refreshErrorVars(ctx.settings, stats.hadError ? { kind: "error" } : {
+		kind: "success",
+		rowCount: lastRowCount
+	});
+	return stats;
+};
+const sendQuery = async (ctx, sqlRaw, opts = {}) => {
+	const sql = stripLeadingCommentsAndWS(sqlRaw);
+	const stats = {
+		rowsAffected: 0,
+		rowsPrinted: 0,
+		fetched: false,
+		hadError: false,
+		durationMs: 0
+	};
+	ctx.settings.lastQuery = sql;
+	if (!ctx.settings.db) {
+		writeError(ctx, "no connection to the server");
+		stats.hadError = true;
+		return stats;
+	}
+	if (readSinglestep(ctx.settings)) {
+		if (!await confirmSinglestep(ctx, sql)) {
+			stats.hadError = true;
+			ctx.settings.lastErrorResult = { message: "command cancelled by user" };
+			return stats;
+		}
+	}
+	const db = ctx.settings.db;
+	const autocommit = readAutocommit(ctx.settings);
+	const onErrorRollback = readOnErrorRollback(ctx.settings);
+	const interactive = !ctx.settings.notty;
+	const started = ctx.settings.timing ? performance.now() : 0;
+	if (!autocommit && readTxStatus(db) === "I" && !commandNoBegin(sql)) try {
+		await db.execSimple("BEGIN");
+	} catch (err) {
+		const message = recordError(ctx, err);
+		writeQueryError(ctx, message);
+		stats.hadError = true;
+		if (ctx.settings.timing) {
+			stats.durationMs = performance.now() - started;
+			ctx.stdout.write("\n" + formatDurationMs(stats.durationMs) + "\n");
+		}
+		return stats;
+	}
+	const savepointActive = onErrorRollback !== "off" && (onErrorRollback === "on" || onErrorRollback === "interactive" && interactive) && readTxStatus(db) === "T";
+	let savepointIssued = false;
+	if (savepointActive) try {
+		await db.execSimple(`SAVEPOINT ${SAVEPOINT_NAME}`);
+		savepointIssued = true;
+	} catch (err) {
+		const message = recordError(ctx, err);
+		writeQueryError(ctx, message);
+		stats.hadError = true;
+		if (ctx.settings.timing) {
+			stats.durationMs = performance.now() - started;
+			ctx.stdout.write("\n" + formatDurationMs(stats.durationMs) + "\n");
+		}
+		return stats;
+	}
+	const out = pickOut$1(ctx, opts.oneShotOut);
+	const fetchCount = readFetchCount(ctx.settings);
+	let lastRowCount = null;
+	try {
+		if (fetchCount > 0 && isSelectCommand(sql)) {
+			const r = await runCursorLoop(ctx, sql, fetchCount, out);
+			stats.rowsAffected = r.rowsAffected;
+			stats.rowsPrinted = r.rowsPrinted;
+			stats.fetched = true;
+			lastRowCount = r.lastRowCount;
+		} else {
+			const results = await db.execSimple(sql);
+			const r = await renderResultSets(ctx, results, out);
+			stats.rowsAffected = r.rowsAffected;
+			stats.rowsPrinted = r.rowsPrinted;
+			lastRowCount = r.lastRowCount;
+		}
+	} catch (err) {
+		const partial = err.partialResults;
+		if (partial && partial.length > 0) try {
+			const r = await renderResultSets(ctx, partial, out);
+			stats.rowsAffected = r.rowsAffected;
+			stats.rowsPrinted = r.rowsPrinted;
+		} catch {}
+		const message = recordError(ctx, err, sql);
+		writeQueryError(ctx, message);
+		stats.hadError = true;
+	}
+	if (savepointIssued) try {
+		if (stats.hadError) {
+			await db.execSimple(`ROLLBACK TO SAVEPOINT ${SAVEPOINT_NAME}`);
+			await db.execSimple(`RELEASE SAVEPOINT ${SAVEPOINT_NAME}`);
+		} else if (!destroysSavepoint(sql) && readTxStatus(db) === "T") await db.execSimple(`RELEASE SAVEPOINT ${SAVEPOINT_NAME}`);
+	} catch (err) {
+		if (!stats.hadError) {
+			const message = recordError(ctx, err);
+			writeQueryError(ctx, message);
+			stats.hadError = true;
+		}
+	}
+	if (stats.hadError && ctx.settings.echo === "errors") {
+		let stmt = sql;
+		while (true) {
+			const before = stmt.length;
+			stmt = stmt.replace(/^[ \t\n\r\f]+/, "");
+			stmt = stmt.replace(/^--[^\n\r]*/, "");
+			if (stmt.length === before) break;
+		}
+		if (stmt.endsWith("\n")) stmt = stmt.slice(0, -1);
+		ctx.stderr.write(`STATEMENT:  ${stmt}\n`);
+	}
+	refreshErrorVars(ctx.settings, stats.hadError ? { kind: "error" } : {
+		kind: "success",
+		rowCount: lastRowCount
+	});
+	if (ctx.settings.timing) {
+		stats.durationMs = performance.now() - started;
+		ctx.stdout.write("\n" + formatDurationMs(stats.durationMs) + "\n");
+	}
+	return stats;
+};
+const psqlExec = async (conn, sql, ignoreError = false) => {
+	try {
+		const sets = await conn.execSimple(sql);
+		if (sets.length === 0) return null;
+		return sets[sets.length - 1];
+	} catch (err) {
+		if (ignoreError) return null;
+		throw err;
+	}
+};
+const __testing = {
+	commandNoBegin,
+	isSelectCommand,
+	destroysSavepoint,
+	peekKeywords,
+	SAVEPOINT_NAME,
+	CURSOR_NAME
+};
+//#endregion
+//#region src/psql/command/cmd_io.ts
+/**
+* psql I/O & control backslash commands.
+*
+* TypeScript port of the following `exec_command_*` functions in upstream
+* PostgreSQL's `src/bin/psql/command.c`:
+*
+*   - `\i`,  `\include`           → exec_command_include          (normal)
+*   - `\ir`, `\include_relative`  → exec_command_include          (relative=true)
+*   - `\o`,  `\out`               → exec_command_out
+*   - `\w`,  `\write`             → exec_command_write
+*   - `\g`                        → exec_command_g
+*   - `\gx`                       → exec_command_g  (force_expanded=true)
+*   - `\gset`                     → exec_command_gset
+*   - `\gdesc`                    → exec_command_gdesc
+*   - `\gexec`                    → exec_command_gexec
+*   - `\watch`                    → exec_command_watch
+*
+* Each is exported as a `BackslashCmdSpec` and registered via
+* {@link registerIoCommands}. The single line that wires us into the
+* default dispatcher lives in `dispatch.ts::defaultRegistry()`.
+*
+* # Integration touch-points and known limitations
+*
+* Several of these commands really want to participate in the mainloop's
+* scanner/printer pipeline. This WP keeps `src/psql/core/mainloop.ts`
+* untouched, so we provide the data structures and let a follow-up WP wire
+* the consumption sites. Limitations documented per-command:
+*
+*   - `\i FILE` enqueues the file's contents on a small input queue
+*     (`./inputQueue.ts`) AND, as a stop-gap, executes the file's SQL
+*     directly via `Connection.execSimple`. Backslash commands embedded in
+*     the file are NOT processed by the scanner; the include is a "best
+*     effort: run as one big SQL blob". Once mainloop adopts the queue API
+*     this becomes a true include.
+*
+*   - `\o FILE` opens a writable stream and stashes it under a symbol on
+*     `settings`. We expose a getter (`getQueryFout`) for the mainloop to
+*     consult; until that wiring happens, query output continues to flow
+*     to the mainloop's `ctx.stdout`. The stash + close-on-rebind logic is
+*     in place and fully tested.
+*
+*   - `\g` (no arg) executes the current queryBuf directly through
+*     `Connection.execSimple` and renders via the aligned printer. This
+*     duplicates a tiny slice of mainloop's send/print pipeline, which is
+*     fine for the bytewise-simple cases this WP needs to support. For
+*     `\g FILE` / `\g |cmd` the output goes through the temporary writer.
+*
+*   - `\gx` toggles `topt.expanded` for the single execution and restores
+*     the prior value in a `try { ... } finally { ... }`.
+*
+*   - `\gset [PREFIX]` executes via `execSimple`, requires the last result
+*     to have exactly one row, and stores `${prefix}${colname}` → value
+*     for each column on `settings.vars`.
+*
+*   - `\gdesc` parses the buffered query with the extended protocol
+*     (Parse + Describe by statement, no Execute), then assembles a
+*     synthetic `Column / Type` ResultSet and renders it through the
+*     active printer (`alignedPrinter` by default; the format picker
+*     honours `\pset format`). Tuples-only mode (`\t on`) and `\o FILE`
+*     redirects ride along automatically because the same ResultSet
+*     goes through the same printer the REPL would use for a query.
+*
+*   - `\gexec` iterates the cells of the last result row-major and feeds
+*     each non-null cell back as SQL through `execSimple`. Each statement's
+*     output is rendered to stdout (or to the active queryFout stash).
+*
+*   - `\watch [INTERVAL]` re-executes the queryBuf every `INTERVAL` seconds
+*     (default 2) until SIGINT or until the iteration count limit is hit.
+*     We hook SIGINT via a transient listener that's removed on completion.
+*     Tests bypass the listener by using an AbortController exposed via
+*     `WATCH_TEST_CONTROLLER`.
+*
+* # Error format
+*
+* Upstream prints `<cmd>: <msg>` to stderr and returns failure. We mirror
+* that and also stash the message on `settings.lastErrorResult` so the
+* mainloop's `writeError()` wrapper can pick it up.
+*/
+const QUERY_FOUT_KEY = Symbol.for("neonctl.psql.queryFout");
+/**
+* Return the currently active queryFout stream (or `null` if none).
+* The mainloop is encouraged to call this in lieu of writing directly to
+* `ctx.stdout` for query results.
+*/
+const getQueryFout = (settings) => {
+	return settings[QUERY_FOUT_KEY]?.stream ?? null;
+};
+const setQueryFout = (settings, entry) => {
+	const stash = settings;
+	if (entry === null) stash[QUERY_FOUT_KEY] = void 0;
+	else stash[QUERY_FOUT_KEY] = entry;
+};
+const closeQueryFout = async (settings) => {
+	const stash = settings;
+	const prev = stash[QUERY_FOUT_KEY];
+	if (prev) {
+		stash[QUERY_FOUT_KEY] = void 0;
+		await prev.close();
+	}
+};
+const WATCH_TEST_CONTROLLER = { ref: null };
+const errResult$1 = (ctx, message) => {
+	ctx.settings.lastErrorResult = { message };
+	const prefix = psqlErrorPrefix(ctx.settings);
+	writeErr(`${prefix}\\${ctx.cmdName}: ${message}\n`);
+	return {
+		status: "error",
+		errorWritten: true
+	};
+};
+/**
+* Reject buffer-consuming commands when an extended pipeline is open. Upstream
+* `exec_command_g` / `gx` / `gset` / `gexec` / `watch` all guard with
+* `PQpipelineStatus(pset.db) != PQ_PIPELINE_OFF` and emit
+* `pg_log_error("\\%s not allowed in pipeline mode", cmd)` (note: no `:`
+* after the command name — different shape from `errResult`).
+*
+* `\gdesc` is the odd one out: upstream uses
+* `pg_log_error("synchronous command execution functions are not allowed in
+* pipeline mode")` because the underlying `PQdescribePrepared`/`PQfn`-style
+* helpers all share that text — the regress baseline asserts this exact
+* wording at three call sites in `psql_pipeline.out`.
+*
+* If the command proceeded it would inject a synchronous Query/Sync into the
+* queue, corrupt the pipeline state, and leave `\endpipeline` waiting forever.
+*
+* Returns `null` when not in pipeline mode (caller proceeds); otherwise
+* returns a populated error result the caller should bubble up.
+*
+* Upstream psql 18.4 leaks gate diagnostics through `pg_log_error_internal`
+* which appends to the libpq result error log on the underlying PGresult;
+* each subsequent gate hit RE-EMITS the full accumulated log plus its own
+* line ("Error messages accumulate and are repeated" — the regress comment
+* is the spec). Two `\gdesc` calls back-to-back therefore emit 3 lines
+* total: 1 for the first call, 2 for the second (one accumulated + one
+* own). Mirror that with a settings-stashed accumulator keyed off the
+* current pipeline session; reset when the pipeline ends.
+*/
+const PIPELINE_GATE_ERRORS_KEY = Symbol.for("neonctl.psql.pipelineGateErrors");
+const getGateErrors = (settings) => {
+	const s = settings;
+	let cur = s[PIPELINE_GATE_ERRORS_KEY];
+	if (!cur) {
+		cur = [];
+		s[PIPELINE_GATE_ERRORS_KEY] = cur;
+	}
+	return cur;
+};
+/**
+* Drop the accumulated pipeline-gate errors. Called from
+* `\endpipeline` so the next pipeline session starts fresh — without
+* this, gate errors from a closed pipeline would leak into the next
+* one.
+*/
+const clearPipelineGateErrors = (settings) => {
+	const s = settings;
+	s[PIPELINE_GATE_ERRORS_KEY] = void 0;
+};
+const pipelineGate = (ctx) => {
+	if (ctx.settings.sendMode !== "extended-pipeline") return null;
+	const message = ctx.cmdName === "gdesc" ? "synchronous command execution functions are not allowed in pipeline mode" : `\\${ctx.cmdName} not allowed in pipeline mode`;
+	ctx.settings.lastErrorResult = { message };
+	const prefix = psqlErrorPrefix(ctx.settings);
+	if (ctx.cmdName === "gdesc") {
+		const log = getGateErrors(ctx.settings);
+		log.push(message);
+		for (const m of log) writeErr(`${prefix}${m}\n`);
+	} else writeErr(`${prefix}${message}\n`);
+	return {
+		status: "error",
+		errorWritten: true
+	};
+};
+/**
+* Set of psql variables upstream marks as "specially treated" — i.e. names
+* that have a substitute / assign hook installed in `startup.c`'s
+* `EstablishVariableSpace`. Used by `\gset` to reject assignments into
+* those names (matching upstream `StoreQueryTuple`'s `VariableHasHook`
+* check). We mirror the upstream list directly so a `\gset IGNORE` into
+* `IGNOREEOF` produces the conformance-expected warning even though our
+* settings.ts hasn't installed the IGNOREEOF / HISTFILE hooks yet — that
+* gap is tracked separately and harmless because the values are read-only
+* for us.
+*/
+const UPSTREAM_SPECIAL_VAR_NAMES = /* @__PURE__ */ new Set([
+	"AUTOCOMMIT",
+	"COMP_KEYWORD_CASE",
+	"ECHO",
+	"ECHO_HIDDEN",
+	"FETCH_COUNT",
+	"HIDE_TABLEAM",
+	"HIDE_TOAST_COMPRESSION",
+	"HISTCONTROL",
+	"HISTFILE",
+	"HISTSIZE",
+	"IGNOREEOF",
+	"ON_ERROR_ROLLBACK",
+	"ON_ERROR_STOP",
+	"PROMPT1",
+	"PROMPT2",
+	"PROMPT3",
+	"QUIET",
+	"SHOW_ALL_RESULTS",
+	"SHOW_CONTEXT",
+	"SINGLELINE",
+	"SINGLESTEP",
+	"VERBOSITY"
+]);
+/**
+* True when `name` is a psql variable that `\gset` must skip with an
+* "attempt to \gset into specially treated variable" message. Combines the
+* registered-hook check (so future hook installations are automatically
+* covered) with the upstream-canonical list above (so cases like
+* IGNOREEOF that aren't hooked in our settings.ts still match upstream's
+* `\gset` behaviour exactly).
+*/
+const isSpeciallyTreatedVar = (settings, name) => settings.vars.hasSubstituteHook(name) || UPSTREAM_SPECIAL_VAR_NAMES.has(name);
+/**
+* Strip line and block comments from `sql` so a COPY-shaped token inside a
+* comment (e.g. dash-dash `COPY t TO STDOUT`) doesn't trigger the
+* `\g FILE` mid-batch sink. Mirrors the cheap normaliser the mainloop uses
+* before wiring `copyOutMidBatchSink`. Embedded literals are NOT stripped —
+* `'COPY x TO STDOUT'` would still match `hasCopyToStdout`, but that's the
+* same false-positive shape upstream tolerates (the regex sweep is
+* intentionally conservative, and the worst-case outcome is "route bytes
+* that never arrive to the file" — harmless).
+*/
+const stripSqlCommentsForCopyScan = (sql) => sql.replace(/\/\*[\s\S]*?\*\//gu, "").replace(/--[^\n]*/gu, "");
+/**
+* True when `sql` contains at least one `COPY ... TO STDOUT` segment.
+* Used by `runGCore` to install a CopyData sink while `\g` / `\gx` /
+* `\g FILE` / `\g |cmd` dispatches a `\;`-chained batch that mixes
+* COPY-OUT with regular SELECT statements. Without the sink the wire
+* layer drops the CopyData bytes on the floor, and the file/pipe ends
+* up with the surrounding tuple results only — see regress/psql lines
+* 5760-5787 (`COPY (SELECT 'foo') TO STDOUT \; COPY (SELECT 'bar') TO
+* STDOUT \g :g_out_file`).
+*/
+const hasCopyToStdout = (sql) => /\bCOPY\b[\s\S]*?\bTO\s+STDOUT\b/iu.test(stripSqlCommentsForCopyScan(sql));
+/**
+* Render a server-side error in upstream psql's 3-line shape (severity +
+* message, then `LINE N:` / `^` re-print) and refresh the `:LAST_ERROR_*`
+* diagnostic variables so a subsequent `\errverbose` sees the rich payload.
+*
+* Mirrors the path that `core/common.ts::writeQueryError` takes for top-level
+* statement errors: capture full ErrorResponse fields onto
+* `settings.lastErrorResult`, render via `formatErrorReport` (honouring
+* VERBOSITY + SHOW_CONTEXT), prefix only the leading severity line with
+* `psql:[<file>:<n>]:`, and update the per-statement diagnostic vars via
+* `refreshErrorVars`.
+*
+* Used by `\g`, `\gx`, `\gset`, `\gdesc`, and `\gexec` so a server-rejected
+* statement dispatched through them renders the same shape vanilla psql
+* produces, instead of the legacy `\<cmd>: <message>` one-liner.
+*/
+const formatServerError = (ctx, err, sql) => {
+	const msg = captureLastError(ctx.settings, err, sql);
+	const e = ctx.settings.lastErrorResult;
+	if (e) {
+		const lines = formatErrorReport(e, ctx.settings.verbosity, ctx.settings.showContext);
+		const prefixed = [psqlErrorPrefix(ctx.settings) + lines[0], ...lines.slice(1)];
+		writeErr(prefixed.join("\n") + "\n");
+	} else {
+		const prefix = psqlErrorPrefix(ctx.settings);
+		writeErr(`${prefix}ERROR:  ${msg}\n`);
+	}
+	refreshErrorVars(ctx.settings, { kind: "error" });
+	return {
+		status: "error",
+		errorWritten: true
+	};
+};
+/**
+* Open a writable destination for `\o` / `\w` / `\g FILE` / `\g |cmd`.
+*
+* `target` of the form `|cmd` spawns `sh -c cmd` and pipes to its stdin.
+* The returned closer waits for the child to exit and resolves to its
+* status + terminating signal (if any) so callers can render
+* `wait_result_to_str`-style errors. Any other string is treated as a
+* file path; the file is truncated.
+*/
+const openWriter = (target) => {
+	if (target.startsWith("|")) {
+		const cmd = target.slice(1);
+		const child = spawn("sh", ["-c", cmd], { stdio: [
+			"pipe",
+			"inherit",
+			"inherit"
+		] });
+		child.stdin.on("error", (err) => {
+			if (err.code !== "EPIPE") throw err;
+		});
+		return {
+			stream: child.stdin,
+			isPipe: true,
+			close: () => new Promise((resolve) => {
+				let settled = false;
+				const finish = (code, signal) => {
+					if (settled) return;
+					settled = true;
+					resolve({
+						exitCode: code,
+						signal
+					});
+				};
+				child.once("close", (code, signal) => {
+					finish(code, signal);
+				});
+				child.once("error", () => {
+					finish(127, null);
+				});
+				if (!child.stdin.destroyed) child.stdin.end();
+			})
+		};
+	}
+	const fd = openSync(target, "w");
+	const stream = createWriteStream(target, {
+		encoding: "utf8",
+		fd,
+		autoClose: false
+	});
+	let writeError = null;
+	stream.on("error", (err) => {
+		writeError = writeError ?? err;
+	});
+	return {
+		stream,
+		isPipe: false,
+		close: () => new Promise((resolve, reject) => {
+			if (writeError !== null) {
+				try {
+					closeSync(fd);
+				} catch {}
+				reject(writeError);
+				return;
+			}
+			stream.end((err) => {
+				if (err) {
+					try {
+						closeSync(fd);
+					} catch {}
+					reject(err);
+					return;
+				}
+				try {
+					fsyncSync(fd);
+				} catch {}
+				try {
+					closeSync(fd);
+				} catch (closeErr) {
+					reject(closeErr);
+					return;
+				}
+				if (platform() === "darwin") {
+					setTimeout(() => {
+						resolve({});
+					}, 25);
+					return;
+				}
+				resolve({});
+			});
+		})
+	};
+};
+/**
+* Map a Node.js errno (`err.code`) to the libc `strerror()` string
+* upstream psql renders in its `pg_log_error("%s: %m", fname)` path.
+*
+* Falls back to `err.message` (with the verbose `ENOENT: ...` prefix
+* stripped if present) so unmapped errno values still surface
+* meaningful text instead of a cryptic Node-internal phrasing.
+*/
+const errnoToStrerror = (err) => {
+	switch (err.code) {
+		case "ENOENT": return "No such file or directory";
+		case "EACCES": return "Permission denied";
+		case "EISDIR": return "Is a directory";
+		case "ENOTDIR": return "Not a directory";
+		case "EEXIST": return "File exists";
+		case "EROFS": return "Read-only file system";
+		case "ELOOP": return "Too many levels of symbolic links";
+		case "ENAMETOOLONG": return "File name too long";
+		case "ENOSPC": return "No space left on device";
+		case "EMFILE": return "Too many open files";
+		case "ENFILE": return "Too many open files in system";
+		case "EIO": return "Input/output error";
+		case "EFBIG": return "File too large";
+		case "EDQUOT": return "Disk quota exceeded";
+		case "EPERM": return "Operation not permitted";
+		case "EINVAL": return "Invalid argument";
+		default: {
+			const m = /^[A-Z]+: ([^,]+)/.exec(err.message);
+			return m ? m[1] : err.message;
+		}
+	}
+};
+/**
+* Emit a file-open failure for `\g FILE`, `\o FILE`, `\w FILE` in the
+* exact shape vanilla psql produces: a bare `<path>: <strerror>` line
+* on stderr, no `\<cmd>:` prefix (matches `pg_log_error` under terse
+* mode, which is what `psql -X` uses).
+*
+* The leading `psql:[<file>:<n>]:` tag is still applied when we're
+* reading SQL from a `\i FILE` include — `psqlErrorPrefix` returns ''
+* for stdin so the line stays bare for the interactive / harness case.
+*
+* Returns an `error` envelope with `errorWritten: true` so the mainloop
+* doesn't write a duplicate `psql: ERROR:` fallback.
+*/
+const reportFileOpenFailure = (ctx, target, err) => {
+	const line = `${target}: ${errnoToStrerror(err)}`;
+	ctx.settings.lastErrorResult = { message: line };
+	const prefix = psqlErrorPrefix(ctx.settings);
+	writeErr(`${prefix}${line}\n`);
+	return {
+		status: "error",
+		errorWritten: true
+	};
+};
+/**
+* True when `err` was thrown by our synchronous `openSync` in
+* {@link openWriter} (i.e. has an errno `code`) and the caller should
+* render it via {@link reportFileOpenFailure} rather than the generic
+* `\<cmd>: <msg>` path.
+*/
+const isFileOpenFailure = (err) => {
+	if (!err || typeof err !== "object") return false;
+	const e = err;
+	return typeof e.code === "string" && e.code.startsWith("E");
+};
+/**
+* Format a child process exit code + signal into upstream psql's
+* `wait_result_to_str` style. Mirrors the C helper in
+* `src/common/wait_error.c`:
+*
+*   - exit code 127  → `command not found`
+*   - exit code 126  → `command was not executable`
+*   - any other code → `child process exited with exit code N`
+*   - terminated by signal S → `child process was terminated by
+*     signal N: <SIG>`
+*
+* Returns null when the child exited cleanly (code 0, no signal).
+*/
+const formatChildWaitResult = (exitCode, signal) => {
+	if (signal) return `child process was terminated by signal: ${signal}`;
+	if (exitCode === null || exitCode === void 0) return null;
+	if (exitCode === 0) return null;
+	if (exitCode === 127) return "command not found";
+	if (exitCode === 126) return "command was not executable";
+	return `child process exited with exit code ${String(exitCode)}`;
+};
+/**
+* Compose the `CommandComplete`-tag line upstream prints for non-tuples-
+* producing results (DDL, DML without RETURNING, COPY). Mirrors
+* `formatCommandTag` in `core/common.ts` — duplicated to avoid the
+* cmd_io → common import cycle. Returns an empty string when no tag is
+* available (e.g. `EmptyQueryResponse` carries `command = ''`).
+*/
+const formatCommandTagText = (rs) => {
+	const command = (rs.command || "").trim();
+	if (command.length === 0) return "";
+	if (command === "INSERT") return `INSERT ${String(rs.oid ?? 0)} ${String(rs.rowCount ?? 0)}`;
+	if (rs.rowCount !== null && rs.rowCount !== void 0) return `${command} ${String(rs.rowCount)}`;
+	return command;
+};
+/**
+* Render a `ResultSet` to the supplied writable stream using the printer
+* picked from the active `\pset format`. Upstream's `do_watch`, `do_gset`,
+* `do_gexec`, and `\i` all funnel results through the standard query
+* output pipeline (`ExecQueryAndProcessResults` → `printQuery`), which
+* honours `\pset format`. Hard-coding the aligned printer here breaks the
+* conformance harness's `psql -A` runs (which expect unaligned tuples-only
+* output for things like `\watch` polled rows).
+*
+* Non-tuples-producing results (CommandComplete with `fields.length === 0`,
+* which covers DDL, DML without RETURNING, and the post-CopyDone tag for
+* `COPY ... TO STDOUT`) are rendered as a single status line instead of
+* the printer's `(0 rows)` empty-table block — matching `renderResultSets`
+* in `core/common.ts`. Tuples-only (`\t`) and quiet (`--quiet`) both
+* suppress the tag entirely.
+*/
+const renderResult = async (settings, rs, out) => {
+	if (rs.copyOutBytes && rs.copyOutBytes.length > 0) for (const chunk of rs.copyOutBytes) out.write(chunk);
+	if (rs.fields.length === 0) {
+		if (!settings.popt.topt.tuplesOnly && !settings.quiet && !rs.copyOutBytes) {
+			const tag = formatCommandTagText(rs);
+			if (tag.length > 0) out.write(`${tag}\n`);
+		}
+		return;
+	}
+	await pickActivePrinter(settings).printQuery(rs, settings.popt, out);
+};
+/**
+* Pick the printer for the active output format. Mirrors `pickPrinter`
+* in `core/common.ts` — duplicated here to avoid the cmd_io → common
+* import cycle (common.ts depends on this file for `getQueryFout`).
+*
+* `wrapped` falls back to the aligned printer (which renders `wrapped`
+* mode itself via `topt.format`).
+*/
+const pickActivePrinter = (settings) => {
+	switch (settings.popt.topt.format) {
+		case "aligned":
+		case "wrapped": return alignedPrinter;
+		case "unaligned": return unalignedPrinter;
+		case "csv": return csvPrinter;
+		case "json": return jsonPrinter;
+		case "html": return htmlPrinter;
+		case "asciidoc": return asciidocPrinter;
+		case "latex": return latexPrinter;
+		case "latex-longtable": return latexLongtablePrinter;
+		case "troff-ms": return troffMsPrinter;
+		default: return alignedPrinter;
+	}
+};
+/**
+* Pick the output target for a query result.
+*
+* Precedence: explicit `oneShot` (e.g. `\g FILE`) > the settings stash
+* (`\o FILE`) > `process.stdout`.
+*/
+const pickOut = (settings, oneShot) => {
+	if (oneShot) return oneShot;
+	return getQueryFout(settings) ?? process.stdout;
+};
+const runInclude = async (ctx, relative) => {
+	const arg = ctx.nextArg("normal");
+	if (arg === null || arg.length === 0) return errResult$1(ctx, "missing required argument");
+	let resolved;
+	if (path.isAbsolute(arg)) resolved = arg;
+	else if (relative && ctx.settings.inputfile) resolved = path.resolve(path.dirname(ctx.settings.inputfile), arg);
+	else resolved = path.resolve(process.cwd(), arg);
+	let contents;
+	try {
+		contents = await promises.readFile(resolved, "utf8");
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		return errResult$1(ctx, msg);
+	}
+	if (!ctx.settings.db) return errResult$1(ctx, "no connection to the server");
+	const trimmed = contents.trim();
+	if (trimmed.length === 0) return { status: "ok" };
+	const priorInputFile = ctx.settings.inputfile;
+	ctx.settings.inputfile = resolved;
+	try {
+		const results = await ctx.settings.db.execSimple(trimmed);
+		const out = pickOut(ctx.settings, null);
+		for (const rs of results) await renderResult(ctx.settings, rs, out);
+		return { status: "ok" };
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		return errResult$1(ctx, msg);
+	} finally {
+		ctx.settings.inputfile = priorInputFile;
+	}
+};
+const cmdInclude = {
+	name: "i",
+	aliases: ["include"],
+	helpKey: "i",
+	run: (ctx) => runInclude(ctx, false)
+};
+const cmdIncludeRel = {
+	name: "ir",
+	aliases: ["include_relative"],
+	helpKey: "ir",
+	run: (ctx) => runInclude(ctx, true)
+};
+const cmdOut = {
+	name: "o",
+	aliases: ["out"],
+	helpKey: "o",
+	async run(ctx) {
+		const arg = ctx.nextArg("filepipe");
+		await closeQueryFout(ctx.settings);
+		if (arg === null || arg.length === 0) return { status: "ok" };
+		try {
+			const entry = openWriter(arg);
+			setQueryFout(ctx.settings, entry);
+			return { status: "ok" };
+		} catch (err) {
+			if (!arg.startsWith("|") && isFileOpenFailure(err)) return reportFileOpenFailure(ctx, arg, err);
+			const msg = err instanceof Error ? err.message : String(err);
+			return errResult$1(ctx, msg);
+		}
+	}
+};
+const cmdWrite = {
+	name: "w",
+	aliases: ["write"],
+	helpKey: "w",
+	async run(ctx) {
+		const arg = ctx.nextArg("filepipe");
+		if (arg === null || arg.length === 0) return errResult$1(ctx, "missing required argument");
+		let entry;
+		try {
+			entry = openWriter(arg);
+		} catch (err) {
+			if (!arg.startsWith("|") && isFileOpenFailure(err)) return reportFileOpenFailure(ctx, arg, err);
+			const msg = err instanceof Error ? err.message : String(err);
+			return errResult$1(ctx, msg);
+		}
+		try {
+			await new Promise((resolve, reject) => {
+				entry.stream.write(ctx.queryBuf, (err) => {
+					if (err) reject(err);
+					else resolve();
+				});
+			});
+		} catch (err) {
+			const isEpipe = err instanceof Error && err.code === "EPIPE";
+			if (!entry.isPipe || !isEpipe) {
+				try {
+					await entry.close();
+				} catch {}
+				const msg = err instanceof Error ? err.message : String(err);
+				return errResult$1(ctx, msg);
+			}
+		}
+		try {
+			const result = await entry.close();
+			if (entry.isPipe) {
+				const msg = formatChildWaitResult(result.exitCode, result.signal);
+				if (msg !== null) {
+					const line = `${arg}: ${msg}`;
+					ctx.settings.lastErrorResult = { message: line };
+					const prefix = psqlErrorPrefix(ctx.settings);
+					writeErr(`${prefix}${line}\n`);
+					return {
+						status: "error",
+						errorWritten: true
+					};
+				}
+			}
+			return { status: "ok" };
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			return errResult$1(ctx, msg);
+		}
+	}
+};
+/**
+* Parse the body of a `\g (option=value option2=value2 ...)` clause —
+* the text between the outer parentheses, already stripped. Options
+* are separated by whitespace; values may be single-quoted to embed
+* spaces. Unquoted values run to the next whitespace.
+*
+* Mirrors upstream's `parse_slash_pgopts_list`. We deliberately stay
+* narrow — the conformance corpus exercises `format=`, `csv_fieldsep=`,
+* and `title=` only.
+*/
+const parseGPsetOptions = (body) => {
+	const out = [];
+	let i = 0;
+	while (i < body.length) {
+		while (i < body.length && /\s/.test(body[i])) i++;
+		if (i >= body.length) break;
+		const optStart = i;
+		while (i < body.length && body[i] !== "=" && !/\s/.test(body[i])) i++;
+		const option = body.slice(optStart, i);
+		if (option.length === 0) break;
+		let value = "";
+		if (body[i] === "=") {
+			i++;
+			if (body[i] === "'") {
+				i++;
+				while (i < body.length && body[i] !== "'") {
+					if (body[i] === "\\" && i + 1 < body.length) {
+						const next = body[i + 1];
+						if (next === "n") value += "\n";
+						else if (next === "t") value += "	";
+						else if (next === "r") value += "\r";
+						else if (next === "\\") value += "\\";
+						else if (next === "'") value += "'";
+						else value += next;
+						i += 2;
+						continue;
+					}
+					value += body[i++];
+				}
+				if (body[i] === "'") i++;
+			} else {
+				const vStart = i;
+				while (i < body.length && !/\s/.test(body[i])) i++;
+				value = body.slice(vStart, i);
+			}
+		}
+		out.push({
+			option,
+			value
+		});
+	}
+	return out;
+};
+const runGCore = async (ctx, forceExpanded) => {
+	const gated = pipelineGate(ctx);
+	if (gated !== null) return gated;
+	const trimmedBuf = stripLeadingCommentsAndWS(ctx.queryBuf);
+	const bufSql = trimmedBuf.trim();
+	let target;
+	let psetOverrides = null;
+	const rawTrimmed = ctx.rawArgs.trimStart();
+	if (rawTrimmed.startsWith("(")) {
+		const close = rawTrimmed.indexOf(")");
+		if (close === -1) return errResult$1(ctx, "missing right parenthesis in \\g options");
+		psetOverrides = parseGPsetOptions(rawTrimmed.slice(1, close).trim());
+		const afterParen = rawTrimmed.slice(close + 1).trim();
+		target = afterParen.length > 0 ? afterParen : null;
+	} else target = ctx.nextArg("filepipe");
+	const sql = bufSql.length > 0 ? bufSql : ctx.settings.lastQuery;
+	const hasPendingNamedBind = stagedNamedBindPresent(ctx.settings);
+	if (sql.length === 0 && !hasPendingNamedBind) return {
+		status: "reset-buf",
+		newBuf: ""
+	};
+	if (!ctx.settings.db) return errResult$1(ctx, "no connection to the server");
+	let oneShot = null;
+	if (target !== null && target.length > 0) try {
+		oneShot = openWriter(target);
+	} catch (err) {
+		if (!target.startsWith("|") && isFileOpenFailure(err)) return reportFileOpenFailure(ctx, target, err);
+		const msg = err instanceof Error ? err.message : String(err);
+		return errResult$1(ctx, msg);
+	}
+	const topt = ctx.settings.popt.topt;
+	const toptSnapshot = { ...topt };
+	if (forceExpanded) topt.expanded = "on";
+	if (psetOverrides) for (const { option, value } of psetOverrides) applyPset(topt, option, value, ctx.cmdName, true);
+	ctx.settings.lastQuery = sql;
+	const bindState = consumeBindState(ctx.settings);
+	let execError = null;
+	let copyOutSinkConn = null;
+	try {
+		const out = pickOut(ctx.settings, oneShot?.stream ?? null);
+		if (bindState?.byName) {
+			const ps = lookupPrepared(ctx.settings, bindState.name);
+			if (!ps) execError = Object.assign(/* @__PURE__ */ new Error(`prepared statement "${bindState.name}" does not exist`), {
+				severity: "ERROR",
+				code: "26000"
+			});
+			else {
+				const rs = await ps.bindAndExecute(bindState.values);
+				await renderResult(ctx.settings, rs, out);
+			}
+		} else if (bindState) {
+			const rs = await ctx.settings.db.query(sql, bindState.values);
+			await renderResult(ctx.settings, rs, out);
+		} else {
+			if (hasCopyToStdout(sql)) {
+				copyOutSinkConn = ctx.settings.db;
+				copyOutSinkConn.copyOutMidBatchSink = (chunk) => {
+					out.write(chunk);
+				};
+			}
+			const results = await ctx.settings.db.execSimple(sql);
+			for (const rs of results) await renderResult(ctx.settings, rs, out);
+		}
+	} catch (err) {
+		execError = err;
+	} finally {
+		Object.assign(topt, toptSnapshot);
+		if (copyOutSinkConn) copyOutSinkConn.copyOutMidBatchSink = null;
+	}
+	let pipeError = null;
+	if (oneShot) try {
+		await oneShot.close();
+	} catch (err) {
+		pipeError = err instanceof Error ? err.message : String(err);
+	}
+	if (execError !== null) return formatServerError(ctx, execError, bufSql.length > 0 ? trimmedBuf : sql);
+	if (pipeError !== null) return errResult$1(ctx, pipeError);
+	return {
+		status: "reset-buf",
+		newBuf: ""
+	};
+};
+const cmdG = {
+	name: "g",
+	helpKey: "g",
+	run: (ctx) => runGCore(ctx, false)
+};
+const cmdGx = {
+	name: "gx",
+	helpKey: "gx",
+	run: (ctx) => runGCore(ctx, true)
+};
+/**
+* `\p` / `\print` — print the query buffer the next `\g` would execute.
+*
+* Mirrors upstream `exec_command_print` in `src/bin/psql/command.c`:
+*
+*   if (query_buf && query_buf->len > 0)
+*     puts(query_buf->data);
+*   else if (previous_buf && previous_buf->len > 0)
+*     puts(previous_buf->data);
+*   else if (!pset.quiet)
+*     puts(_("Query buffer is empty."));
+*
+* Buffer-vs-previous-buffer precedence matters for the regress sequence:
+*
+*     SELECT 1;       -- executes, previous_buf := "SELECT 1;"
+*     \p              -- queryBuf empty → prints previous_buf
+*     SELECT 2 \r     -- queryBuf="SELECT 2 ", \r resets to "" without
+*                     -- touching previous_buf
+*     \p              -- queryBuf still empty → prints previous_buf
+*     SELECT 3 \p     -- queryBuf="SELECT 3 ", non-empty → prints queryBuf
+*
+* Implementation notes:
+*
+*  - We use `settings.lastQuery` as the previous-buffer source. Upstream
+*    tracks `previous_buf` independently of `pset.last_query`, but our
+*    `lastQuery` is set at the exact same point upstream sets
+*    `previous_buf` (the dispatch site in `SendQuery`-equivalent code paths
+*    in `core/common.ts` and `cmd_io.ts`'s `\g` implementation), so the
+*    semantics match for every shape exercised by the conformance corpus.
+*  - We must NOT clear queryBuf — return `status: 'ok'` so the mainloop
+*    leaves the buffer untouched. The user is inspecting, not executing.
+*  - `puts()` appends a trailing newline. We use `writeOut` and append `\n`
+*    explicitly to match.
+*/
+const cmdPrint = {
+	name: "p",
+	aliases: ["print"],
+	helpKey: "p",
+	run: (ctx) => {
+		if (ctx.queryBuf.trim().length > 0) writeOut(`${ctx.queryBuf}\n`);
+		else if (ctx.settings.lastQuery.length > 0) writeOut(`${ctx.settings.lastQuery}\n`);
+		else if (!ctx.settings.quiet) writeOut("Query buffer is empty.\n");
+		return Promise.resolve({ status: "ok" });
+	}
+};
+const formatCell = (value) => {
+	if (value === null || value === void 0) return "";
+	if (typeof value === "string") return value;
+	if (Buffer.isBuffer(value)) return value.toString("utf8");
+	if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") return String(value);
+	try {
+		return JSON.stringify(value);
+	} catch {
+		return "";
+	}
+};
+const cmdGset = {
+	name: "gset",
+	helpKey: "gset",
+	async run(ctx) {
+		const gated = pipelineGate(ctx);
+		if (gated !== null) return gated;
+		const trimmedBuf = stripLeadingCommentsAndWS(ctx.queryBuf);
+		const bufSql = trimmedBuf.trim();
+		const prefix = ctx.nextArg("normal") ?? "";
+		const sql = bufSql.length > 0 ? bufSql : ctx.settings.lastQuery.trim();
+		if (sql.length === 0) return {
+			status: "reset-buf",
+			newBuf: ""
+		};
+		if (!ctx.settings.db) return errResult$1(ctx, "no connection to the server");
+		ctx.settings.lastQuery = sql;
+		let results;
+		try {
+			results = await ctx.settings.db.execSimple(sql);
+		} catch (err) {
+			return formatServerError(ctx, err, bufSql.length > 0 ? trimmedBuf : sql);
+		}
+		if (results.length > 1) {
+			const out = pickOut(ctx.settings, null);
+			for (let i = 0; i < results.length - 1; i++) await renderResult(ctx.settings, results[i], out);
+		}
+		const lastRs = results[results.length - 1];
+		if (!lastRs || lastRs.fields.length === 0) return {
+			status: "reset-buf",
+			newBuf: ""
+		};
+		const rs = lastRs;
+		if (rs.rows.length === 0) {
+			ctx.settings.lastErrorResult = { message: "no rows returned for \\gset" };
+			const errPrefix = psqlErrorPrefix(ctx.settings);
+			writeErr(`${errPrefix}no rows returned for \\gset\n`);
+			return {
+				status: "error",
+				errorWritten: true
+			};
+		}
+		if (rs.rows.length > 1) {
+			ctx.settings.lastErrorResult = { message: "more than one row returned for \\gset" };
+			const errPrefix = psqlErrorPrefix(ctx.settings);
+			writeErr(`${errPrefix}more than one row returned for \\gset\n`);
+			return {
+				status: "error",
+				errorWritten: true
+			};
+		}
+		const row = rs.rows[0];
+		for (let i = 0; i < rs.fields.length; i++) {
+			const fieldName = rs.fields[i].name;
+			const name = `${prefix}${fieldName}`;
+			const cell = row[i];
+			const isNull = cell === null || cell === void 0;
+			if (isSpeciallyTreatedVar(ctx.settings, name)) {
+				const errPrefix = psqlErrorPrefix(ctx.settings);
+				writeErr(`${errPrefix}attempt to \\gset into specially treated variable "${name}" ignored\n`);
+				continue;
+			}
+			if (isNull) {
+				ctx.settings.vars.unset(name);
+				continue;
+			}
+			const value = formatCell(cell);
+			if (!ctx.settings.vars.set(name, value)) {
+				ctx.settings.lastErrorResult = { message: `invalid variable name: "${fieldName}"` };
+				const errPrefix = psqlErrorPrefix(ctx.settings);
+				writeErr(`${errPrefix}invalid variable name: "${fieldName}"\n`);
+				return {
+					status: "error",
+					errorWritten: true
+				};
+			}
+		}
+		return {
+			status: "reset-buf",
+			newBuf: ""
+		};
+	}
+};
+/**
+* Build the SQL that resolves each describe-result column's `Type` via
+* `pg_catalog.format_type(typoid, typmod)`. We feed the names + OIDs
+* + typmods through a `VALUES` literal so the server does the formatting
+* for us — the same query upstream issues from `describeFieldsByType`.
+*
+* Returns null when there are zero fields (caller emits `(0 rows)` form
+* by hand because PostgreSQL rejects an empty VALUES list).
+*/
+const buildGdescFormatQuery = (fields) => {
+	if (fields.length === 0) return null;
+	return `SELECT name AS "Column", pg_catalog.format_type(tp, tpm) AS "Type" FROM (VALUES ${fields.map((f, i) => {
+		const safeName = f.name.replace(/'/gu, "''");
+		const oid = String(f.dataTypeID >>> 0);
+		const typmod = String(f.dataTypeModifier | 0);
+		return `(${String(i)}, '${safeName}', ${oid}::oid, ${typmod}::int4)`;
+	}).join(", ")}) AS x(_idx, name, tp, tpm) ORDER BY _idx`;
+};
+/**
+* Field descriptors for the synthetic `Column / Type` ResultSet that
+* `\gdesc` emits when format_type resolution fails or yields nothing.
+*
+* We fall back to the field's raw OID so the user still sees a value.
+*/
+const GDESC_SYNTHETIC_FIELDS = [{
+	name: "Column",
+	tableID: 0,
+	columnID: 0,
+	dataTypeID: 25,
+	dataTypeSize: -1,
+	dataTypeModifier: -1,
+	format: 0
+}, {
+	name: "Type",
+	tableID: 0,
+	columnID: 0,
+	dataTypeID: 25,
+	dataTypeSize: -1,
+	dataTypeModifier: -1,
+	format: 0
+}];
+const buildSyntheticGdescResultSet = (rows) => ({
+	command: "SELECT",
+	rowCount: rows.length,
+	oid: null,
+	fields: GDESC_SYNTHETIC_FIELDS,
+	rows,
+	notices: []
+});
+const cmdGdesc = {
+	name: "gdesc",
+	helpKey: "gdesc",
+	async run(ctx) {
+		const gated = pipelineGate(ctx);
+		if (gated !== null) return gated;
+		const trimmedBuf = stripLeadingCommentsAndWS(ctx.queryBuf);
+		const sql = trimmedBuf.trim();
+		if (sql.length === 0) {
+			process.stdout.write("The command has no result, or the result has no columns.\n");
+			refreshErrorVars(ctx.settings, {
+				kind: "success",
+				rowCount: 0
+			});
+			return {
+				status: "reset-buf",
+				newBuf: ""
+			};
+		}
+		if (!ctx.settings.db) return errResult$1(ctx, "no connection to the server");
+		ctx.settings.lastQuery = sql;
+		let fields;
+		try {
+			const stmt = await ctx.settings.db.prepare("", sql);
+			fields = await stmt.describe();
+			try {
+				await stmt.close();
+			} catch {}
+		} catch (err) {
+			return formatServerError(ctx, err, trimmedBuf);
+		}
+		if (fields.length === 0) {
+			process.stdout.write("The command has no result, or the result has no columns.\n");
+			refreshErrorVars(ctx.settings, {
+				kind: "success",
+				rowCount: 0
+			});
+			return {
+				status: "reset-buf",
+				newBuf: ""
+			};
+		}
+		let rows;
+		const formatQuery = buildGdescFormatQuery(fields);
+		if (formatQuery === null) rows = [];
+		else {
+			const fallbackRows = () => fields.map((f) => [f.name, String(f.dataTypeID)]);
+			try {
+				const sets = await ctx.settings.db.execSimple(formatQuery);
+				const last = sets[sets.length - 1];
+				rows = last && last.rows.length > 0 ? last.rows : fallbackRows();
+			} catch {
+				rows = fallbackRows();
+			}
+		}
+		const rs = buildSyntheticGdescResultSet(rows);
+		const printer = pickActivePrinter(ctx.settings);
+		const out = pickOut(ctx.settings, null);
+		try {
+			await printer.printQuery(rs, ctx.settings.popt, out);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			return errResult$1(ctx, msg);
+		}
+		refreshErrorVars(ctx.settings, {
+			kind: "success",
+			rowCount: rs.rowCount
+		});
+		return {
+			status: "reset-buf",
+			newBuf: ""
+		};
+	}
+};
+const cmdGexec = {
+	name: "gexec",
+	helpKey: "gexec",
+	async run(ctx) {
+		const gated = pipelineGate(ctx);
+		if (gated !== null) return gated;
+		const trimmedBuf = stripLeadingCommentsAndWS(ctx.queryBuf);
+		const bufSql = trimmedBuf.trim();
+		const sql = bufSql.length > 0 ? bufSql : ctx.settings.lastQuery.trim();
+		if (sql.length === 0) return {
+			status: "reset-buf",
+			newBuf: ""
+		};
+		if (!ctx.settings.db) return errResult$1(ctx, "no connection to the server");
+		ctx.settings.lastQuery = sql;
+		let firstPass;
+		try {
+			firstPass = await ctx.settings.db.execSimple(sql);
+		} catch (err) {
+			return formatServerError(ctx, err, trimmedBuf);
+		}
+		const tupled = firstPass.filter((r) => r.fields.length > 0);
+		if (tupled.length === 0) return {
+			status: "reset-buf",
+			newBuf: ""
+		};
+		const out = pickOut(ctx.settings, null);
+		const echo = ctx.settings.echo;
+		const shouldEcho = echo === "all" || echo === "queries";
+		for (const rs of tupled) for (const row of rs.rows) for (const cell of row) {
+			if (cell === null || cell === void 0) continue;
+			const statement = formatCell(cell).trim();
+			if (statement.length === 0) continue;
+			if (shouldEcho) out.write(statement + "\n");
+			try {
+				const nested = await ctx.settings.db.execSimple(statement);
+				for (const sub of nested) if (sub.fields.length > 0) await renderResult(ctx.settings, sub, out);
+			} catch (err) {
+				formatServerError(ctx, err, statement);
+				if (ctx.settings.onErrorStop) return {
+					status: "error",
+					errorWritten: true
+				};
+			}
+		}
+		return {
+			status: "reset-buf",
+			newBuf: ""
+		};
+	}
+};
+const sleepCancellable = (ms, signal) => new Promise((resolve) => {
+	const timer = setTimeout(() => {
+		signal.removeEventListener("abort", onAbort);
+		resolve();
+	}, ms);
+	const onAbort = () => {
+		clearTimeout(timer);
+		signal.removeEventListener("abort", onAbort);
+		resolve();
+	};
+	if (signal.aborted) {
+		clearTimeout(timer);
+		resolve();
+		return;
+	}
+	signal.addEventListener("abort", onAbort);
+});
+/**
+* Strictly parse a non-negative finite float.
+*
+* Returns the parsed number, or `null` for any of:
+*   - empty string
+*   - non-numeric trailing characters (e.g. `10ab`)
+*   - negative values (e.g. `-10`)
+*   - out-of-range / non-finite results (e.g. `10e400` → Infinity)
+*
+* Used to validate `\watch` intervals and the `WATCH_INTERVAL` variable.
+*/
+const parseStrictNonNegativeFloat = (raw) => {
+	if (raw.length === 0) return null;
+	if (!/^[+-]?(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?$/.test(raw)) return null;
+	const value = parseFloat(raw);
+	if (!Number.isFinite(value)) return null;
+	if (value < 0) return null;
+	return value;
+};
+/**
+* Parse a strict non-negative integer (no exponent, no fractional).
+* Used for `c=` and `m=` / `min_rows=` argument values.
+*/
+const parseStrictNonNegativeInt = (raw) => {
+	if (raw.length === 0) return null;
+	if (!/^\d+$/.test(raw)) return null;
+	const value = parseInt(raw, 10);
+	if (!Number.isFinite(value)) return null;
+	return value;
+};
+/**
+* Default `\watch` interval (seconds). Mirrors upstream
+* `DEFAULT_WATCH_INTERVAL`. Exported so `defaultSettings` can substitute
+* it when the user unsets the `WATCH_INTERVAL` variable — upstream's
+* `watch_interval_substitute_hook` reseeds the value to `2` on null.
+*/
+const DEFAULT_WATCH_INTERVAL = "2";
+/**
+* Render `\watch`'s per-iteration timestamp in upstream psql's
+* `ctime`-style layout: `Day Mon DD HH:MM:SS YYYY` (e.g. `Mon May 25
+* 19:41:55 2026`). Upstream calls `strftime("%c", &tm)` with the C locale;
+* we reproduce the field order in vanilla English so the output matches
+* regardless of the host locale.
+*
+* Exported only for unit-testing the format ladder.
+*/
+const WEEKDAYS = [
+	"Sun",
+	"Mon",
+	"Tue",
+	"Wed",
+	"Thu",
+	"Fri",
+	"Sat"
+];
+const MONTHS = [
+	"Jan",
+	"Feb",
+	"Mar",
+	"Apr",
+	"May",
+	"Jun",
+	"Jul",
+	"Aug",
+	"Sep",
+	"Oct",
+	"Nov",
+	"Dec"
+];
+const pad2 = (n) => n < 10 ? `0${String(n)}` : String(n);
+const formatWatchTimestamp = (now) => {
+	return `${WEEKDAYS[now.getDay()]} ${MONTHS[now.getMonth()]} ${pad2(now.getDate())} ${pad2(now.getHours())}:${pad2(now.getMinutes())}:${pad2(now.getSeconds())} ${String(now.getFullYear())}`;
+};
+/**
+* Upper bound on the `WATCH_INTERVAL` variable and the positional interval
+* — matches upstream which rejects "out of range" values. Upstream uses
+* `strtod` and rejects ±Infinity; we tighten further so a single watch loop
+* cannot sleep for longer than ~100 hours, which catches obvious typos
+* without breaking legitimate slow polls.
+*/
+const WATCH_INTERVAL_MAX_SECONDS = 36e4;
+/**
+* Resolve the effective default `\watch` interval from the `WATCH_INTERVAL`
+* psql variable. Returns the parsed value, the documented default
+* (`DEFAULT_WATCH_INTERVAL`), or an `error` envelope if the variable is set
+* but parses out of range.
+*/
+const resolveWatchIntervalDefault = (settings) => {
+	const raw = settings.vars.get("WATCH_INTERVAL") ?? "2";
+	const parsed = parseStrictNonNegativeFloat(raw);
+	if (parsed === null || parsed > WATCH_INTERVAL_MAX_SECONDS) return { error: `WATCH_INTERVAL "${raw}" is out of range` };
+	return { value: parsed };
+};
+/**
+* Spawn the `\watch` pager for the full duration of the polling loop.
+*
+* Upstream `do_watch` wraps the loop in a single `popen` of
+* `PSQL_WATCH_PAGER`. It deliberately ignores `PSQL_PAGER` and `$PAGER`:
+*
+*   > we ignore the regular PSQL_PAGER or PAGER environment variables,
+*   > because traditional pagers probably won't be very useful for
+*   > showing a stream of results.
+*
+* Mirror that here. Reading from `$PAGER` would silently hijack
+* `\watch` output for any user whose shell sets `PAGER=less` (the
+* common default), which makes the loop's output disappear into a
+* subprocess that diff harnesses can't capture.
+*
+* We use a single `sh -c <pager>` spawn so the user can set the
+* variable to a full command string (`less -R`, `tee /tmp/log`, …)
+* without the caller having to tokenise it. EPIPE on the stdin pipe is
+* swallowed for the same reason as in `openWriter`: the user may quit
+* `less` while we still have writes pending in the next iteration.
+*
+* Returns `null` when `PSQL_WATCH_PAGER` is unset or whitespace-only
+* (upstream's "no pager" rule), so the caller falls back to the normal
+* output target.
+*/
+const openWatchPager = () => {
+	const cmd = process.env.PSQL_WATCH_PAGER ?? "";
+	if (cmd.trim().length === 0) return null;
+	const child = spawn("sh", ["-c", cmd], { stdio: [
+		"pipe",
+		"inherit",
+		"inherit"
+	] });
+	child.stdin.on("error", (err) => {
+		if (err.code !== "EPIPE") throw err;
+	});
+	return {
+		stream: child.stdin,
+		close: () => new Promise((resolve) => {
+			if (child.exitCode !== null || child.signalCode !== null) {
+				resolve();
+				return;
+			}
+			let settled = false;
+			const finish = () => {
+				if (settled) return;
+				settled = true;
+				resolve();
+			};
+			child.once("close", finish);
+			child.once("error", finish);
+			if (!child.stdin.destroyed) try {
+				child.stdin.end();
+			} catch (err) {
+				if (err.code !== "EPIPE") finish();
+			}
+		})
+	};
+};
+const cmdWatch = {
+	name: "watch",
+	helpKey: "watch",
+	async run(ctx) {
+		const gated = pipelineGate(ctx);
+		if (gated !== null) return gated;
+		const trimmedBuf = stripLeadingCommentsAndWS(ctx.queryBuf);
+		const sql = trimmedBuf.trim();
+		if (sql.length === 0) return errResult$1(ctx, "no query buffer");
+		if (!ctx.settings.db) return errResult$1(ctx, "no connection to the server");
+		let intervalSet = false;
+		let interval = null;
+		let iterSet = false;
+		let iterMax = 0;
+		let minRowsSet = false;
+		let minRows = 0;
+		let positionalSeen = false;
+		while (true) {
+			const arg = ctx.nextArg("normal");
+			if (arg === null) break;
+			if (arg.length === 0) continue;
+			const eqIdx = arg.indexOf("=");
+			if (eqIdx > 0) {
+				const key = arg.slice(0, eqIdx);
+				const value = arg.slice(eqIdx + 1);
+				if (key === "i") {
+					if (intervalSet) return errResult$1(ctx, "interval value is specified more than once");
+					const parsed = parseStrictNonNegativeFloat(value);
+					if (parsed === null || parsed > WATCH_INTERVAL_MAX_SECONDS) return errResult$1(ctx, `incorrect interval value "${value}"`);
+					interval = parsed;
+					intervalSet = true;
+					continue;
+				}
+				if (key === "c") {
+					if (iterSet) return errResult$1(ctx, "iteration count is specified more than once");
+					const parsed = parseStrictNonNegativeInt(value);
+					if (parsed === null || parsed === 0) return errResult$1(ctx, `incorrect iteration count "${value}"`);
+					iterMax = parsed;
+					iterSet = true;
+					continue;
+				}
+				if (key === "m" || key === "min_rows") {
+					if (minRowsSet) return errResult$1(ctx, "minimum row count specified more than once");
+					const parsed = parseStrictNonNegativeInt(value);
+					if (parsed === null) return errResult$1(ctx, `incorrect minimum row count "${value}"`);
+					minRows = parsed;
+					minRowsSet = true;
+					continue;
+				}
+				return errResult$1(ctx, `unrecognized option "${key}"`);
+			}
+			if (positionalSeen || intervalSet) return errResult$1(ctx, "interval value is specified more than once");
+			const parsed = parseStrictNonNegativeFloat(arg);
+			if (parsed === null || parsed > WATCH_INTERVAL_MAX_SECONDS) return errResult$1(ctx, `incorrect interval value "${arg}"`);
+			interval = parsed;
+			intervalSet = true;
+			positionalSeen = true;
+		}
+		if (interval === null) {
+			const resolved = resolveWatchIntervalDefault(ctx.settings);
+			if ("error" in resolved) return errResult$1(ctx, resolved.error);
+			interval = resolved.value;
+		}
+		const intervalMs = Math.round(interval * 1e3);
+		const controller = WATCH_TEST_CONTROLLER.ref ?? new AbortController();
+		const sigintHandler = () => {
+			controller.abort();
+		};
+		const installedSigint = WATCH_TEST_CONTROLLER.ref === null;
+		if (installedSigint) process.once("SIGINT", sigintHandler);
+		const pager = openWatchPager();
+		const out = pager?.stream ?? pickOut(ctx.settings, null);
+		try {
+			let iter = 0;
+			while (!controller.signal.aborted) {
+				iter++;
+				const stamp = formatWatchTimestamp(/* @__PURE__ */ new Date());
+				out.write(`${stamp} (every ${String(interval)}s)\n\n`);
+				let lastRowCount = 0;
+				try {
+					const results = await ctx.settings.db.execSimple(sql);
+					for (const rs of results) if (rs.fields.length > 0) {
+						await renderResult(ctx.settings, rs, out);
+						lastRowCount = rs.rows.length;
+					}
+				} catch (err) {
+					return formatServerError(ctx, err, trimmedBuf);
+				}
+				if (iterSet && iter >= iterMax) break;
+				if (minRowsSet && lastRowCount < minRows) break;
+				if (controller.signal.aborted) break;
+				if (intervalMs > 0) await sleepCancellable(intervalMs, controller.signal);
+			}
+			if (!pager) out.write("\n");
+			return {
+				status: "reset-buf",
+				newBuf: ""
+			};
+		} finally {
+			if (installedSigint) process.removeListener("SIGINT", sigintHandler);
+			if (pager) await pager.close();
+		}
+	}
+};
+const registerIoCommands = (registry) => {
+	registry.register(cmdInclude);
+	registry.register(cmdIncludeRel);
+	registry.register(cmdOut);
+	registry.register(cmdWrite);
+	registry.register(cmdG);
+	registry.register(cmdGx);
+	registry.register(cmdPrint);
+	registry.register(cmdGset);
+	registry.register(cmdGdesc);
+	registry.register(cmdGexec);
+	registry.register(cmdWatch);
+};
+//#endregion
+//#region src/psql/command/cmd_pipeline.ts
+/**
+* psql pipeline / extended-query backslash commands (WP-21).
+*
+* Implements the subset of upstream psql's "pipeline mode" backslash commands
+* that drive the extended protocol directly. These are typically used together
+* with the existing `\g` flow: a `\bind` (or `\parse`) command stashes
+* parameter / statement state on the {@link BackslashContext}'s settings via
+* a Symbol-keyed slot; when the mainloop then sees a `;` (or a `\g`), it can
+* notice the stashed state and route the query through
+* `Connection.query(sql, params)` instead of `execSimple`.
+*
+* Because the mainloop integration is owned by other WPs (and was deliberately
+* left untouched here), this module exposes both the command specs AND a
+* small helper, {@link getPipelineState}, that the mainloop will use to
+* consult the stashed state. The commands operate on the buffered query the
+* same way `\g` does — they execute or queue the buffer and reset it.
+*
+* Commands shipped:
+*
+*   \bind [VALUE ...]        stash params for next ; / \g
+*   \bind_named NAME [V ...] stash params + named prepared statement
+*   \parse NAME              prepare current query buffer as NAME
+*   \close_prepared NAME     Close('S', NAME)
+*   \startpipeline           begin a pipeline session (settings.sendMode)
+*   \endpipeline             end the pipeline session, drain results
+*   \syncpipeline            send Sync mid-pipeline
+*   \sendpipeline            submit the current buffered query w/o waiting
+*   \flushrequest            send Flush
+*   \flush                   alias for \flushrequest
+*   \getresults [N]          drain pending pipeline results
+*   \gdesc                   describe-without-execute the buffered query
+*
+* The set is registered in bulk via {@link registerPipelineCommands}.
+*/
+const BIND_STATE_KEY = Symbol.for("neonctl.psql.bindState");
+const PIPELINE_KEY = Symbol.for("neonctl.psql.pipeline");
+const PREPARED_BY_NAME_KEY = Symbol.for("neonctl.psql.preparedByName");
+const stashOf = (settings) => settings;
+/** Read (and clear) the pending bind params, if any. */
+const consumeBindState = (settings) => {
+	const s = stashOf(settings);
+	const cur = s[BIND_STATE_KEY] ?? null;
+	s[BIND_STATE_KEY] = void 0;
+	return cur;
+};
+/**
+* Peek at the bind stash without consuming. Used by `\g` to decide
+* whether to skip the "empty buffer, no prior query" no-op guard:
+* when a `\bind_named NAME` is pending, the prepared statement carries
+* the SQL server-side so no buffer text is needed.
+*/
+const stagedNamedBindPresent = (settings) => {
+	const cur = stashOf(settings)[BIND_STATE_KEY];
+	return !!cur && cur.byName;
+};
+/** Stash a PreparedStatement for later `\bind_named NAME \g` lookup. */
+const stashPrepared = (settings, name, ps) => {
+	const s = stashOf(settings);
+	let map = s[PREPARED_BY_NAME_KEY];
+	if (!map) {
+		map = /* @__PURE__ */ new Map();
+		s[PREPARED_BY_NAME_KEY] = map;
+	}
+	map.set(name, ps);
+};
+/** Look up a previously-stashed PreparedStatement by name. */
+const lookupPrepared = (settings, name) => {
+	return stashOf(settings)[PREPARED_BY_NAME_KEY]?.get(name) ?? null;
+};
+/** Drop a stashed PreparedStatement (after `\close_prepared`). */
+const dropPrepared = (settings, name) => {
+	const map = stashOf(settings)[PREPARED_BY_NAME_KEY];
+	if (map) map.delete(name);
+};
+/** Peek at the current pipeline session (or null). */
+const getPipelineState = (settings) => stashOf(settings)[PIPELINE_KEY] ?? null;
+const readCounter = (settings, name) => {
+	const raw = settings.vars.get(name);
+	if (raw === void 0) return 0;
+	const n = parseInt(raw, 10);
+	return Number.isFinite(n) && n >= 0 ? n : 0;
+};
+const setCounter = (settings, name, value) => {
+	settings.vars.set(name, String(Math.max(0, value)));
+};
+const bumpCounter = (settings, name, delta) => {
+	setCounter(settings, name, readCounter(settings, name) + delta);
+};
+const resetPipelineCounters = (settings) => {
+	setCounter(settings, "PIPELINE_COMMAND_COUNT", 0);
+	setCounter(settings, "PIPELINE_SYNC_COUNT", 0);
+	setCounter(settings, "PIPELINE_RESULT_COUNT", 0);
+};
+/**
+* Wrap `Pipeline.execute` so each enqueued Execute message bumps
+* `PIPELINE_COMMAND_COUNT`. The wrapping covers both call sites:
+*
+*  - `cmdSendPipeline` (this file) — `\sendpipeline`.
+*  - `dispatchSendQuery` (mainloop) — implicit `;`-queries while pipeline
+*    is active. Mainloop calls `ps.session.execute('', 0)` so the wrapper
+*    fires automatically without mainloop knowing about the var store.
+*
+* The wrapper preserves the original function's `this` binding via `apply`.
+*/
+const wrapSessionForCounters = (session, settings) => {
+	const origExecute = session.execute.bind(session);
+	session.execute = (name, maxRows) => {
+		bumpCounter(settings, "PIPELINE_COMMAND_COUNT", 1);
+		return origExecute(name, maxRows);
+	};
+	return session;
+};
+const errResult = (ctx, message) => {
+	ctx.settings.lastErrorResult = { message };
+	writeErr(`\\${ctx.cmdName}: ${message}\n`);
+	return {
+		status: "error",
+		errorWritten: true
+	};
+};
+/**
+* Coerce any thrown / rejected value into a printable string. The
+* extended-protocol driver in `PgConnection` rejects with raw
+* ConnectError records (`{severity, code, message, detail, ...}`) —
+* not `Error` instances — so `String(err)` would produce
+* `[object Object]` in the conformance output. We probe for a
+* `.message` property (covering both `Error` and the ConnectError
+* shape) and fall back to JSON.stringify only when there's no
+* message field at all.
+*/
+const errorToMessage = (err) => {
+	if (err instanceof Error) return err.message;
+	if (err !== null && typeof err === "object" && "message" in err && typeof err.message === "string") return err.message;
+	try {
+		return JSON.stringify(err);
+	} catch {
+		return String(err);
+	}
+};
+/**
+* Render a pipeline-collected ConnectError to stderr in the upstream
+* shape: a `SEVERITY:  message` line, followed by optional `DETAIL:` /
+* `HINT:` / `CONTEXT:` lines (each on its own line). Matches the
+* subset of `formatErrorReport`-style output the conformance corpus
+* expects from `\endpipeline` for non-FATAL pipeline errors. We
+* inline a minimal renderer here rather than importing the full
+* `formatErrorReport` from `cmd_meta` because we always want the
+* "default verbosity, no LINE/caret context" form — pipeline errors
+* arrive after the buffered query has been reset and we don't carry
+* the originating SQL position through `session.lastError`.
+*/
+const renderPipelineError = (err) => {
+	if (err === null || typeof err !== "object") {
+		writeErr(`ERROR:  ${errorToMessage(err)}\n`);
+		return;
+	}
+	const e = err;
+	if (e.pipelineAborted) {
+		writeErr(`${e.message ?? "Pipeline aborted, command did not run"}\n`);
+		return;
+	}
+	const severity = e.severity ?? "ERROR";
+	const message = e.message ?? "";
+	writeErr(`${severity}:  ${message}\n`);
+	if (e.detail) writeErr(`DETAIL:  ${e.detail}\n`);
+	if (e.hint) writeErr(`HINT:  ${e.hint}\n`);
+	if (e.where) writeErr(`CONTEXT:  ${e.where}\n`);
+};
+const readAllArgs = (ctx) => {
+	const out = [];
+	for (;;) {
+		const arg = ctx.nextArg("normal");
+		if (arg === null) break;
+		out.push(arg);
+	}
+	return out;
+};
+const cmdBind = {
+	name: "bind",
+	helpKey: "bind",
+	run(ctx) {
+		const values = readAllArgs(ctx);
+		stashOf(ctx.settings)[BIND_STATE_KEY] = {
+			name: "",
+			values,
+			byName: false
+		};
+		return Promise.resolve({ status: "ok" });
+	}
+};
+const cmdBindNamed = {
+	name: "bind_named",
+	helpKey: "bind_named",
+	run(ctx) {
+		const name = ctx.nextArg("normal");
+		if (name === null) {
+			stashOf(ctx.settings)[BIND_STATE_KEY] = void 0;
+			return Promise.resolve(errResult(ctx, "missing required argument"));
+		}
+		const values = readAllArgs(ctx);
+		stashOf(ctx.settings)[BIND_STATE_KEY] = {
+			name,
+			values,
+			byName: true
+		};
+		return Promise.resolve({ status: "ok" });
+	}
+};
+const cmdParse = {
+	name: "parse",
+	helpKey: "parse",
+	async run(ctx) {
+		const name = ctx.nextArg("normal");
+		if (name === null) return errResult(ctx, "missing required argument");
+		const sql = ctx.queryBuf;
+		if (sql.trim().length === 0) return errResult(ctx, "no query buffer");
+		if (!ctx.settings.db) return errResult(ctx, "no connection to the server");
+		const pipelineActive = getPipelineState(ctx.settings);
+		if (pipelineActive !== null) try {
+			const session = pipelineActive.session;
+			if (typeof session.parseSlot === "function") await session.parseSlot(name, sql, []);
+			else await session.parse(name, sql, []);
+			ctx.settings.lastQuery = sql;
+			bumpCounter(ctx.settings, "PIPELINE_COMMAND_COUNT", 1);
+			return {
+				status: "reset-buf",
+				newBuf: ""
+			};
+		} catch (err) {
+			return errResult(ctx, errorToMessage(err));
+		}
+		try {
+			const ps = await ctx.settings.db.prepare(name, sql);
+			stashPrepared(ctx.settings, name, ps);
+			ctx.settings.lastQuery = sql;
+			return {
+				status: "reset-buf",
+				newBuf: ""
+			};
+		} catch (err) {
+			return errResult(ctx, errorToMessage(err));
+		}
+	}
+};
+const cmdClosePrepared = {
+	name: "close_prepared",
+	helpKey: "close_prepared",
+	async run(ctx) {
+		const name = ctx.nextArg("normal");
+		if (name === null) return errResult(ctx, "missing required argument");
+		const db = ctx.settings.db;
+		if (!db) return errResult(ctx, "no connection to the server");
+		const ps = getPipelineState(ctx.settings);
+		if (ps !== null) try {
+			const session = ps.session;
+			if (typeof session.closeSlot === "function") await session.closeSlot(name);
+			else await session.close(name);
+			bumpCounter(ctx.settings, "PIPELINE_COMMAND_COUNT", 1);
+			dropPrepared(ctx.settings, name);
+			return { status: "ok" };
+		} catch (err) {
+			return errResult(ctx, errorToMessage(err));
+		}
+		try {
+			if (db.closePreparedStatement) await db.closePreparedStatement(name);
+			else await (await db.prepare(name, "SELECT 1")).close();
+			dropPrepared(ctx.settings, name);
+			return { status: "ok" };
+		} catch (err) {
+			return errResult(ctx, errorToMessage(err));
+		}
+	}
+};
+const cmdStartPipeline = {
+	name: "startpipeline",
+	helpKey: "startpipeline",
+	run(ctx) {
+		if (!ctx.settings.db) return Promise.resolve(errResult(ctx, "no connection to the server"));
+		if (getPipelineState(ctx.settings) !== null) return Promise.resolve({ status: "ok" });
+		try {
+			const session = wrapSessionForCounters(ctx.settings.db.pipeline(), ctx.settings);
+			stashOf(ctx.settings)[PIPELINE_KEY] = {
+				session,
+				pending: [],
+				drainedCount: 0
+			};
+			ctx.settings.sendMode = "extended-pipeline";
+			resetPipelineCounters(ctx.settings);
+			return Promise.resolve({ status: "ok" });
+		} catch (err) {
+			return Promise.resolve(errResult(ctx, errorToMessage(err)));
+		}
+	}
+};
+const cmdEndPipeline = {
+	name: "endpipeline",
+	helpKey: "endpipeline",
+	async run(ctx) {
+		const ps = getPipelineState(ctx.settings);
+		if (!ps) {
+			ctx.settings.lastErrorResult = { message: "cannot send pipeline when not in pipeline mode" };
+			writeErr("cannot send pipeline when not in pipeline mode\n");
+			return {
+				status: "error",
+				errorWritten: true
+			};
+		}
+		try {
+			const alreadyDrained = ps.drainedCount;
+			const session = ps.session;
+			const cmdSlotsSnapshot = Array.isArray(session.cmdSlots) ? session.cmdSlots.slice() : [];
+			const fetchCountActive = (ctx.settings.vars.get("FETCH_COUNT") ?? "0") !== "0";
+			const sets = await ps.session.end();
+			stashOf(ctx.settings)[PIPELINE_KEY] = void 0;
+			ctx.settings.sendMode = "extended-query";
+			resetPipelineCounters(ctx.settings);
+			clearPipelineGateErrors(ctx.settings);
+			const settled = await Promise.allSettled(cmdSlotsSnapshot);
+			let errorRendered = false;
+			const entries = settled.length > 0 ? settled : sets.map((rs) => ({
+				status: "fulfilled",
+				value: rs
+			}));
+			const sliceForError = entries.slice(alreadyDrained);
+			const realLastError = (() => {
+				for (const r of sliceForError) {
+					if (r.status !== "rejected") continue;
+					const reason = r.reason;
+					if (!(typeof reason === "object" && reason !== null && reason.pipelineAborted === true)) return reason;
+				}
+				return null;
+			})() ?? (() => {
+				const le = session.lastError;
+				if (le === null || le === void 0) return null;
+				if (typeof le === "object" && le.pipelineAborted) return null;
+				return le;
+			})();
+			for (let i = alreadyDrained; i < entries.length; i++) {
+				const r = entries[i];
+				if (r.status === "fulfilled") {
+					const rs = r.value;
+					for (const n of rs.notices) {
+						let out = `${n.severity}:  ${n.message}\n`;
+						if (n.detail !== void 0) out += `DETAIL:  ${n.detail}\n`;
+						if (n.hint !== void 0) out += `HINT:  ${n.hint}\n`;
+						writeErr(out);
+					}
+					const isSyncOrPlaceholder = rs.fields.length === 0 && rs.command === "" && rs.rows.length === 0;
+					const isCommandOnly = rs.fields.length === 0 && rs.rows.length === 0 && rs.command !== "";
+					if (!isSyncOrPlaceholder && !isCommandOnly) if (rs.fields.length === 0 && rs.rows.length > 0) {
+						if (!ctx.settings.popt.topt.tuplesOnly) {
+							process.stdout.write("--\n");
+							process.stdout.write(`(${rs.rows.length} ${rs.rows.length === 1 ? "row" : "rows"})\n\n`);
+						}
+					} else await alignedPrinter.printQuery(rs, ctx.settings.popt, process.stdout);
+				} else if (!errorRendered) {
+					const reason = r.reason;
+					const isAborted = typeof reason === "object" && reason !== null && reason.pipelineAborted === true;
+					if (fetchCountActive) writeErr("fetching results in chunked mode failed\n");
+					if (isAborted && realLastError !== null) renderPipelineError(realLastError);
+					else if (isAborted) writeErr("Pipeline aborted, command did not run\n");
+					else renderPipelineError(reason);
+					errorRendered = true;
+				}
+			}
+			if (!errorRendered) {
+				const lastErr = session.lastError;
+				if (lastErr !== null && lastErr !== void 0) {
+					if (fetchCountActive) writeErr("fetching results in chunked mode failed\n");
+					renderPipelineError(lastErr);
+				}
+			}
+			return { status: "ok" };
+		} catch (err) {
+			stashOf(ctx.settings)[PIPELINE_KEY] = void 0;
+			ctx.settings.sendMode = "extended-query";
+			resetPipelineCounters(ctx.settings);
+			clearPipelineGateErrors(ctx.settings);
+			return errResult(ctx, errorToMessage(err));
+		}
+	}
+};
+const cmdSyncPipeline = {
+	name: "syncpipeline",
+	helpKey: "syncpipeline",
+	async run(ctx) {
+		const ps = getPipelineState(ctx.settings);
+		if (!ps) return errResult(ctx, "no pipeline active");
+		try {
+			await ps.session.sync();
+			const queued = readCounter(ctx.settings, "PIPELINE_COMMAND_COUNT");
+			setCounter(ctx.settings, "PIPELINE_COMMAND_COUNT", 0);
+			bumpCounter(ctx.settings, "PIPELINE_RESULT_COUNT", queued);
+			bumpCounter(ctx.settings, "PIPELINE_SYNC_COUNT", 1);
+			return { status: "ok" };
+		} catch (err) {
+			return errResult(ctx, errorToMessage(err));
+		}
+	}
+};
+const cmdFlushRequest = {
+	name: "flushrequest",
+	helpKey: "flushrequest",
+	async run(ctx) {
+		const ps = getPipelineState(ctx.settings);
+		if (!ps) return errResult(ctx, "no pipeline active");
+		try {
+			await ps.session.flush();
+			const queued = readCounter(ctx.settings, "PIPELINE_COMMAND_COUNT");
+			setCounter(ctx.settings, "PIPELINE_COMMAND_COUNT", 0);
+			bumpCounter(ctx.settings, "PIPELINE_RESULT_COUNT", queued);
+			return { status: "ok" };
+		} catch (err) {
+			return errResult(ctx, errorToMessage(err));
+		}
+	}
+};
+const cmdFlush = {
+	name: "flush",
+	helpKey: "flush",
+	run(ctx) {
+		return cmdFlushRequest.run(ctx);
+	}
+};
+const cmdSendPipeline = {
+	name: "sendpipeline",
+	helpKey: "sendpipeline",
+	async run(ctx) {
+		const ps = getPipelineState(ctx.settings);
+		if (!ps) {
+			consumeBindState(ctx.settings);
+			ctx.settings.lastErrorResult = { message: "\\sendpipeline not allowed outside of pipeline mode" };
+			writeErr("\\sendpipeline not allowed outside of pipeline mode\n");
+			return {
+				status: "error",
+				errorWritten: true
+			};
+		}
+		const bind = consumeBindState(ctx.settings);
+		if (bind === null) {
+			ctx.settings.lastErrorResult = { message: "\\sendpipeline must be used after \\bind or \\bind_named" };
+			writeErr("\\sendpipeline must be used after \\bind or \\bind_named\n");
+			return {
+				status: "error",
+				errorWritten: true
+			};
+		}
+		const sql = ctx.queryBuf.trim();
+		const stmtName = bind.name;
+		const params = bind.values;
+		if (!bind.byName && sql.length === 0) return errResult(ctx, "no query buffer");
+		try {
+			if (!bind.byName) await ps.session.parse("", sql, []);
+			await ps.session.bind(stmtName, params);
+			const exec = (async () => {
+				await ps.session.execute("", 0);
+				return {
+					command: "",
+					rowCount: null,
+					oid: null,
+					fields: [],
+					rows: [],
+					notices: []
+				};
+			})();
+			ps.pending.push(exec);
+			return {
+				status: "reset-buf",
+				newBuf: ""
+			};
+		} catch (err) {
+			return errResult(ctx, errorToMessage(err));
+		}
+	}
+};
+const cmdGetResults = {
+	name: "getresults",
+	helpKey: "getresults",
+	async run(ctx) {
+		const ps = getPipelineState(ctx.settings);
+		const arg = ctx.nextArg("normal");
+		let requested = null;
+		if (arg !== null && arg.length > 0) {
+			const parsed = parseInt(arg, 10);
+			if (!Number.isFinite(parsed) || parsed < 0) return errResult(ctx, "invalid number of requested results");
+			requested = parsed;
+		}
+		if (!ps) {
+			process.stdout.write("No pending results to get\n");
+			return { status: "ok" };
+		}
+		const syncAvailable = readCounter(ctx.settings, "PIPELINE_SYNC_COUNT");
+		const resultAvailable = readCounter(ctx.settings, "PIPELINE_RESULT_COUNT");
+		const available = syncAvailable + resultAvailable;
+		if (available === 0) {
+			process.stdout.write("No pending results to get\n");
+			return { status: "ok" };
+		}
+		const n = requested === null || requested === 0 ? available : Math.min(requested, available);
+		const session = ps.session;
+		const slots = Array.isArray(session.cmdSlots) ? session.cmdSlots : [];
+		const start = ps.drainedCount;
+		const end = start + n;
+		const slice = slots.slice(start, end);
+		ps.drainedCount = end;
+		ps.pending.splice(0, n);
+		try {
+			const settled = await Promise.allSettled(slice);
+			const sliceErr = (() => {
+				for (const r of settled) {
+					if (r.status !== "rejected") continue;
+					const reason = r.reason;
+					if (!(typeof reason === "object" && reason !== null && reason.pipelineAborted === true)) return reason;
+				}
+				return null;
+			})();
+			const sessPeek = session;
+			const realErr = sliceErr ?? (typeof sessPeek.peekRealError === "function" ? await sessPeek.peekRealError() : null);
+			let errorRenderedHere = false;
+			let walkedItems = 0;
+			let syncsDrained = 0;
+			let resultsDrained = 0;
+			for (const r of settled) {
+				walkedItems++;
+				if (r.status !== "fulfilled") {
+					resultsDrained++;
+					if (!errorRenderedHere) {
+						const reason = r.reason;
+						if (typeof reason === "object" && reason !== null && reason.pipelineAborted === true && realErr !== null) renderPipelineError(realErr);
+						else renderPipelineError(reason);
+						errorRenderedHere = true;
+					}
+					continue;
+				}
+				const rs = r.value;
+				for (const n of rs.notices) {
+					let out = `${n.severity}:  ${n.message}\n`;
+					if (n.detail !== void 0) out += `DETAIL:  ${n.detail}\n`;
+					if (n.hint !== void 0) out += `HINT:  ${n.hint}\n`;
+					writeErr(out);
+				}
+				if (rs.fields.length === 0 && rs.command === "" && rs.rows.length === 0) {
+					syncsDrained++;
+					continue;
+				}
+				resultsDrained++;
+				if (rs.fields.length === 0 && rs.rows.length > 0) {
+					if (!ctx.settings.popt.topt.tuplesOnly) {
+						process.stdout.write("--\n");
+						process.stdout.write(`(${rs.rows.length} ${rs.rows.length === 1 ? "row" : "rows"})\n\n`);
+					}
+				} else if (rs.fields.length > 0) await alignedPrinter.printQuery(rs, ctx.settings.popt, process.stdout);
+			}
+			const sessMark = session;
+			if (typeof sessMark.markDrained === "function") sessMark.markDrained(end);
+			if (errorRenderedHere) {
+				const sessAny = session;
+				if (typeof sessAny.clearLastError === "function") sessAny.clearLastError();
+			}
+			if (walkedItems === 0) {
+				const ddata = Math.min(n, resultAvailable);
+				resultsDrained = ddata;
+				syncsDrained = n - ddata;
+			} else {
+				const actualSyncs = Math.min(syncsDrained, syncAvailable);
+				const extraResults = syncsDrained - actualSyncs;
+				syncsDrained = actualSyncs;
+				resultsDrained += extraResults;
+			}
+			bumpCounter(ctx.settings, "PIPELINE_SYNC_COUNT", -syncsDrained);
+			bumpCounter(ctx.settings, "PIPELINE_RESULT_COUNT", -resultsDrained);
+			return { status: "ok" };
+		} catch (err) {
+			return errResult(ctx, errorToMessage(err));
+		}
+	}
+};
+const registerPipelineCommands = (registry) => {
+	registry.register(cmdBind);
+	registry.register(cmdBindNamed);
+	registry.register(cmdParse);
+	registry.register(cmdClosePrepared);
+	registry.register(cmdStartPipeline);
+	registry.register(cmdEndPipeline);
+	registry.register(cmdSyncPipeline);
+	registry.register(cmdFlushRequest);
+	registry.register(cmdFlush);
+	registry.register(cmdSendPipeline);
+	registry.register(cmdGetResults);
+};
+//#endregion
+export { cmdPrint as A, psqlExec as B, cmdGdesc as C, cmdInclude as D, cmdGx as E, registerIoCommands as F, writeQueryError as G, renderResultSet as H, __testing as I, captureLastError as L, cmdWrite as M, formatWatchTimestamp as N, cmdIncludeRel as O, getQueryFout as P, executeAndPrint as R, cmdG as S, cmdGset as T, sendQuery as U, refreshErrorVars as V, stripLeadingCommentsAndWS as W, stagedNamedBindPresent as _, cmdFlush as a, WATCH_TEST_CONTROLLER as b, cmdParse as c, cmdSyncPipeline as d, consumeBindState as f, registerPipelineCommands as g, lookupPrepared as h, cmdEndPipeline as i, cmdWatch as j, cmdOut as k, cmdSendPipeline as l, getPipelineState as m, cmdBindNamed as n, cmdFlushRequest as o, dropPrepared as p, cmdClosePrepared as r, cmdGetResults as s, cmdBind as t, cmdStartPipeline as u, stashPrepared as v, cmdGexec as w, clearPipelineGateErrors as x, DEFAULT_WATCH_INTERVAL as y, pickOut$1 as z };