neonctl 2.22.0 → 2.23.0

package/psql/core/startup.js

@@ -0,0 +1,840 @@
+/**
+ * psql startup-args parser + applier.
+ *
+ * TypeScript port of `parse_psql_options()` / the top of `main()` in
+ * `src/bin/psql/startup.c`. Two responsibilities:
+ *
+ *   1. `parseStartupArgs(argv)` — hand-written getopt_long-equivalent that
+ *      walks the argv array once, decoding short (`-c`) and long (`--command`)
+ *      options, and accumulates an ordered list of `-c`/`-f` actions plus a
+ *      bag of settings flags. Positional arguments follow the upstream
+ *      `[DBNAME [USERNAME]]` rule.
+ *
+ *      We hand-roll the parser instead of pulling in `yargs` (or similar)
+ *      because upstream psql has subtle precedence rules — actions are
+ *      ordered, `-v NAME` without `=` deletes the variable, `-X` interacts
+ *      with `.psqlrc` discovery, etc. The parser stays under ~250 LOC and is
+ *      fully covered by unit tests.
+ *
+ *   2. `applyStartupArgs(args, settings, baseConnect)` — mutates `settings`
+ *      (and its var store) in-place to reflect parsed flags, then returns
+ *      the connect options the caller should use plus the ordered list of
+ *      pre-REPL actions to execute (currently just `-c` / `-f`).
+ *
+ * Out-of-scope for WP-26 but the table mentions them so they're listed below:
+ *   - `-1` / `--single-transaction` — we accept and record on the args but
+ *     do not wire its semantics in the caller. Tracked for a follow-up.
+ *   - `-C` — accepted as a no-op (since-PG17 connection-check skip).
+ *   - `-l` / `--list` — recorded; the caller may use it later to short-circuit
+ *     the REPL with a `\l` and exit. Not wired here.
+ *   - `-L logfile`, `-o output` — recorded on args. Routing into the printer
+ *     is owned by other WPs (logfile streaming and output redirection).
+ *   - `--help[=topic]` — returns a ParseError with `kind: 'help'` and the
+ *     help text already rendered as `message`. Caller writes and exits 0.
+ *   - `-V` / `--version` — returns `kind: 'version'` with the version string.
+ *     Caller writes and exits 0.
+ *
+ * Help/version text is rendered through `./help.ts` so the formatting stays
+ * in lock-step with `\?` output (WP-18). The version string mirrors upstream
+ * `psql (PostgreSQL) PG_VERSION` and is currently hard-coded — the embedded
+ * psql doesn't have a build-system PG_VERSION constant. A follow-up could
+ * surface the real PG version from a const, but for now we expose the
+ * embedded build's version label.
+ */
+import { envConnectionDefaults, libpqConnectionDefaults, looksLikeConnectionString, mergeConnectOptions, parseConninfo, parseConnectionUriPartial, serviceEntryToConnectOptions, } from '../index.js';
+import { lookupPgPass } from '../io/pgpass.js';
+import { setStartupVars } from './syncVars.js';
+import { helpVariables, slashUsage, usage } from './help.js';
+// ---------------------------------------------------------------------------
+// Internal helpers.
+// ---------------------------------------------------------------------------
+/** Short options that consume the next argv slot (or attached value). */
+const SHORT_WITH_ARG = new Set([
+    'c',
+    'd',
+    'f',
+    'F',
+    'h',
+    'L',
+    'o',
+    'p',
+    'P',
+    'R',
+    'T',
+    'U',
+    'v',
+]);
+/** Short flags (no argument). */
+const SHORT_NO_ARG = new Set([
+    'a',
+    'A',
+    'b',
+    'C',
+    'e',
+    'E',
+    'H',
+    'l',
+    'n',
+    'q',
+    's',
+    'S',
+    't',
+    'V',
+    'w',
+    'W',
+    'x',
+    'X',
+    'z',
+    '0',
+    '1',
+    '?',
+]);
+/** Long option → canonical short equivalent (or sentinel string). */
+const LONG_MAP = {
+    'echo-all': 'a',
+    'no-align': 'A',
+    command: 'c',
+    dbname: 'd',
+    'echo-queries': 'e',
+    'echo-errors': 'b',
+    'echo-hidden': 'E',
+    file: 'f',
+    'field-separator': 'F',
+    'field-separator-zero': 'z',
+    host: 'h',
+    html: 'H',
+    list: 'l',
+    'log-file': 'L',
+    'no-readline': 'n',
+    'single-transaction': '1',
+    output: 'o',
+    port: 'p',
+    pset: 'P',
+    quiet: 'q',
+    'record-separator': 'R',
+    'record-separator-zero': '0',
+    'single-step': 's',
+    'single-line': 'S',
+    'tuples-only': 't',
+    'table-attr': 'T',
+    username: 'U',
+    set: 'v',
+    variable: 'v',
+    version: 'V',
+    'no-password': 'w',
+    password: 'W',
+    expanded: 'x',
+    'no-psqlrc': 'X',
+    'no-pager': '__no_pager__',
+    'on-error-stop': '__on_error_stop__',
+    help: '__help__',
+    csv: '__csv__',
+};
+/** Long options that REQUIRE an attached value (or one in the next argv). */
+const LONG_WITH_ARG = new Set([
+    'command',
+    'dbname',
+    'file',
+    'field-separator',
+    'host',
+    'log-file',
+    'output',
+    'port',
+    'pset',
+    'record-separator',
+    'table-attr',
+    'username',
+    'set',
+    'variable',
+]);
+/** Long options whose value is optional (only attached with `=`). */
+const LONG_OPTIONAL_ARG = new Set(['help', 'echo-hidden']);
+const blankArgs = () => ({
+    actions: [],
+    variables: [],
+    noPsqlrc: false,
+    noReadline: false,
+    echoAll: false,
+    echoHidden: 'off',
+    echoErrors: false,
+    echoQueries: false,
+    quiet: false,
+    singleline: false,
+    singlestep: false,
+    noAlign: false,
+    noPager: false,
+    htmlMode: false,
+    tuplesOnly: false,
+    expanded: false,
+    csvOutput: false,
+    onErrorStop: false,
+    fieldSepZero: false,
+    recordSepZero: false,
+    pset: [],
+    list: false,
+    singleTransaction: false,
+    help: false,
+    version: false,
+    positional: [],
+});
+const renderToString = (fn) => {
+    const chunks = [];
+    const sink = {
+        write(chunk) {
+            chunks.push(typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8'));
+            return true;
+        },
+    };
+    fn(sink);
+    return chunks.join('');
+};
+const renderHelp = (topic) => {
+    if (topic === undefined || topic === 'options') {
+        return renderToString((out) => {
+            usage(out);
+        });
+    }
+    if (topic === 'commands') {
+        return renderToString((out) => {
+            slashUsage(out, false);
+        });
+    }
+    if (topic === 'variables') {
+        return renderToString((out) => {
+            helpVariables(out);
+        });
+    }
+    return '';
+};
+/**
+ * Version label for the embedded TypeScript psql. This is the "client"
+ * identifier — the analogue of upstream psql's compiled-in `PG_VERSION`.
+ * The embedded psql is not a real PostgreSQL build, so we track our own
+ * implementation version here. It seeds the `VERSION_NAME` psql var (and,
+ * via {@link setStartupVars}, the numeric `VERSION_NUM`); keep it as a
+ * `MAJOR.MINOR.PATCH` string so the numeric mapping stays meaningful. Bump
+ * alongside meaningful behaviour changes to the embedded psql.
+ */
+export const CLIENT_VERSION = '1.0.0';
+// `psql --version` / `-V` output. Mirrors upstream's `psql (PostgreSQL)
+// <PG_VERSION>` SHAPE (tools parse the leading `psql (PostgreSQL)`), with an
+// `embedded-ts` label in place of a real PG build number since this is a
+// reimplementation, not a compiled psql. Distinct from the `:VERSION` psql
+// variable (the client-identity string seeded from CLIENT_VERSION).
+const VERSION_STRING = `psql (PostgreSQL) embedded-ts (neonctl ${CLIENT_VERSION})`;
+const pushAction = (acts, a) => {
+    acts.push(a);
+};
+const pushVariable = (vars, raw) => {
+    const eq = raw.indexOf('=');
+    if (eq < 0) {
+        // psql treats `-v NAME` (no value) as "delete this variable". We surface
+        // an empty value; the caller decides whether to set or unset. Tests
+        // verify both shapes.
+        vars.push({ name: raw, value: '' });
+        return;
+    }
+    vars.push({ name: raw.slice(0, eq), value: raw.slice(eq + 1) });
+};
+/**
+ * `-d VALUE` resolution. libpq accepts three shapes for the value:
+ *
+ *   1. Bare database name (no `=`, no `postgres[ql]://` prefix) — set
+ *      `args.database` directly. This is by far the common case.
+ *   2. Connection URI (`postgresql://…` / `postgres://…`) — parse it and
+ *      lift the fields it specifies onto `args` (host, port, user, etc.).
+ *   3. Conninfo key=value pairs separated by whitespace — same, but parsed
+ *      via `parseConninfo`.
+ *
+ * The test corpus for upstream `001_basic.pl` uses shape (3) to open a
+ * walsender connection: `-d "dbname=postgres replication=database"`. We
+ * fold any conninfo-only fields (currently only `replication`) onto a
+ * dedicated `args.replication` slot that `applyStartupArgs` threads into
+ * `ConnectOptions.replication`.
+ */
+const applyDashD = (args, value) => {
+    if (!looksLikeConnectionString(value)) {
+        args.database = value;
+        return;
+    }
+    // Use the *partial* URI parser, NOT parseConnectionUri: the latter applies
+    // libpq's lowest-priority OS-user fallback (`user = $USER`, `database =
+    // user`) eagerly, and those non-undefined defaults would then land in the
+    // top-priority argv layer and override `PGUSER` / `PGDATABASE` (review #7).
+    // The partial parser returns only the keys the URI actually specified.
+    const parsed = value.startsWith('postgresql://') || value.startsWith('postgres://')
+        ? parseConnectionUriPartial(value)
+        : parseConninfo(value);
+    // Keep the whole partial (incl. ssl*/channelBinding/hostaddr/requireAuth)
+    // so the connection layer carries it (review #6).
+    args.dashD = { ...(args.dashD ?? {}), ...parsed };
+    // Continue to mirror the core target fields onto the flag slots so the
+    // positional-arg / dbname-username precedence logic below sees them. Only
+    // when not already set by an explicit flag (flags win over -d).
+    if (parsed.host !== undefined && args.host === undefined) {
+        args.host = parsed.host;
+    }
+    if (parsed.port !== undefined && args.port === undefined) {
+        args.port = parsed.port;
+    }
+    if (parsed.user !== undefined && args.user === undefined) {
+        args.user = parsed.user;
+    }
+    if (parsed.password !== undefined && args.password === undefined) {
+        args.password = parsed.password;
+    }
+    if (parsed.database !== undefined && args.database === undefined) {
+        args.database = parsed.database;
+    }
+    if (parsed.replication !== undefined) {
+        args.replication = parsed.replication;
+    }
+};
+// ---------------------------------------------------------------------------
+// parseStartupArgs.
+// ---------------------------------------------------------------------------
+export const parseStartupArgs = (argv) => {
+    const args = blankArgs();
+    const actions = [];
+    const variables = [];
+    const pset = [];
+    let i = 0;
+    const n = argv.length;
+    const needValue = (flagDisplay) => {
+        if (i + 1 >= n) {
+            return {
+                kind: 'missing-arg',
+                message: `option requires an argument -- ${flagDisplay}`,
+            };
+        }
+        i += 1;
+        return argv[i];
+    };
+    const applyShort = (letter, attachedValue, flagDisplay) => {
+        // Resolve the value: either attached (already next to the flag) or the
+        // next argv slot. If the flag does not take an argument, attachedValue
+        // must be undefined.
+        const takesArg = SHORT_WITH_ARG.has(letter);
+        let value;
+        if (takesArg) {
+            if (attachedValue !== undefined) {
+                value = attachedValue;
+            }
+            else {
+                const v = needValue(flagDisplay);
+                if (typeof v !== 'string')
+                    return v;
+                value = v;
+            }
+        }
+        else if (attachedValue !== undefined) {
+            // A value was attached to a short flag that doesn't accept one. Treat
+            // this as an invalid-option error (matches `getopt_long` behaviour
+            // for clusters like `-Xy` where `X` doesn't take an argument — flex
+            // continues to `y`; we keep it strict for clarity).
+            return {
+                kind: 'invalid-option',
+                message: `option does not take an argument -- ${letter}`,
+            };
+        }
+        switch (letter) {
+            case 'a':
+                args.echoAll = true;
+                return null;
+            case 'A':
+                args.noAlign = true;
+                return null;
+            case 'b':
+                args.echoErrors = true;
+                return null;
+            case 'C':
+                // Since-PG17 "skip connection check" — no-op for our use.
+                return null;
+            case 'c':
+                pushAction(actions, { kind: 'command', sql: value });
+                return null;
+            case 'd':
+                applyDashD(args, value);
+                return null;
+            case 'e':
+                args.echoQueries = true;
+                return null;
+            case 'E':
+                args.echoHidden = 'on';
+                return null;
+            case 'f':
+                pushAction(actions, { kind: 'file', path: value });
+                return null;
+            case 'F':
+                args.fieldSep = value;
+                args.fieldSepZero = false;
+                return null;
+            case 'h':
+                args.host = value;
+                return null;
+            case 'H':
+                args.htmlMode = true;
+                return null;
+            case 'l':
+                args.list = true;
+                return null;
+            case 'L':
+                args.log = value;
+                return null;
+            case 'n':
+                args.noReadline = true;
+                return null;
+            case 'o':
+                args.output = value;
+                return null;
+            case 'p': {
+                const p = Number.parseInt(value, 10);
+                if (!Number.isFinite(p) || p <= 0 || p > 65535) {
+                    return {
+                        kind: 'invalid-value',
+                        message: `invalid port number: "${value}"`,
+                    };
+                }
+                args.port = p;
+                return null;
+            }
+            case 'P':
+                pset.push(value);
+                return null;
+            case 'q':
+                args.quiet = true;
+                return null;
+            case 'R':
+                args.recordSep = value;
+                args.recordSepZero = false;
+                return null;
+            case 's':
+                args.singlestep = true;
+                return null;
+            case 'S':
+                args.singleline = true;
+                return null;
+            case 't':
+                args.tuplesOnly = true;
+                return null;
+            case 'T':
+                // -T TEXT → push a synthetic pset directive so it routes through
+                // the same `\pset tableattr` plumbing.
+                pset.push(`tableattr=${value}`);
+                return null;
+            case 'U':
+                args.user = value;
+                return null;
+            case 'v':
+                pushVariable(variables, value);
+                return null;
+            case 'V':
+                return {
+                    kind: 'version',
+                    message: VERSION_STRING,
+                };
+            case 'w':
+                args.promptPassword = false;
+                return null;
+            case 'W':
+                args.promptPassword = true;
+                return null;
+            case 'x':
+                args.expanded = true;
+                return null;
+            case 'X':
+                args.noPsqlrc = true;
+                return null;
+            case 'z':
+                args.fieldSepZero = true;
+                return null;
+            case '0':
+                args.recordSepZero = true;
+                return null;
+            case '1':
+                args.singleTransaction = true;
+                return null;
+            case '?':
+                return {
+                    kind: 'help',
+                    message: renderHelp(undefined),
+                };
+            default:
+                return {
+                    kind: 'invalid-option',
+                    message: `invalid option -- ${letter}`,
+                };
+        }
+    };
+    // ---- Main loop. -------------------------------------------------------
+    while (i < n) {
+        const tok = argv[i];
+        if (tok === '--') {
+            // End of options. Everything after is positional.
+            i += 1;
+            while (i < n) {
+                args.positional.push(argv[i]);
+                i += 1;
+            }
+            break;
+        }
+        if (tok.startsWith('--')) {
+            // Long option: `--name` or `--name=value`.
+            const eq = tok.indexOf('=');
+            const name = eq < 0 ? tok.slice(2) : tok.slice(2, eq);
+            const attached = eq < 0 ? undefined : tok.slice(eq + 1);
+            // Special-case the long-only synthetic options first.
+            if (name === 'csv') {
+                if (attached !== undefined) {
+                    return {
+                        kind: 'invalid-option',
+                        message: `option does not take an argument: --${name}`,
+                    };
+                }
+                args.csvOutput = true;
+                i += 1;
+                continue;
+            }
+            if (name === 'no-pager') {
+                if (attached !== undefined) {
+                    return {
+                        kind: 'invalid-option',
+                        message: `option does not take an argument: --${name}`,
+                    };
+                }
+                args.noPager = true;
+                i += 1;
+                continue;
+            }
+            if (name === 'on-error-stop') {
+                if (attached !== undefined) {
+                    return {
+                        kind: 'invalid-option',
+                        message: `option does not take an argument: --${name}`,
+                    };
+                }
+                args.onErrorStop = true;
+                variables.push({ name: 'ON_ERROR_STOP', value: 'on' });
+                i += 1;
+                continue;
+            }
+            if (name === 'help') {
+                const topic = attached;
+                if (topic !== undefined &&
+                    topic !== 'options' &&
+                    topic !== 'commands' &&
+                    topic !== 'variables') {
+                    return {
+                        kind: 'invalid-option',
+                        message: `unrecognized help topic: ${topic}`,
+                    };
+                }
+                return { kind: 'help', message: renderHelp(topic) };
+            }
+            if (name === 'echo-hidden') {
+                if (attached === undefined) {
+                    args.echoHidden = 'on';
+                }
+                else if (attached === 'noexec') {
+                    args.echoHidden = 'noexec';
+                }
+                else if (attached === '' || attached === 'on') {
+                    args.echoHidden = 'on';
+                }
+                else {
+                    return {
+                        kind: 'invalid-value',
+                        message: `invalid value for --echo-hidden: "${attached}"`,
+                    };
+                }
+                i += 1;
+                continue;
+            }
+            const short = LONG_MAP[name];
+            if (short === undefined) {
+                return {
+                    kind: 'invalid-option',
+                    message: `unrecognized option: --${name}`,
+                };
+            }
+            const requiresArg = LONG_WITH_ARG.has(name);
+            const optionalArg = LONG_OPTIONAL_ARG.has(name);
+            let value = attached;
+            if (requiresArg && value === undefined) {
+                if (i + 1 >= n) {
+                    return {
+                        kind: 'missing-arg',
+                        message: `option requires an argument: --${name}`,
+                    };
+                }
+                i += 1;
+                value = argv[i];
+            }
+            else if (!requiresArg && !optionalArg && value !== undefined) {
+                return {
+                    kind: 'invalid-option',
+                    message: `option does not take an argument: --${name}`,
+                };
+            }
+            const err = applyShort(short, value, `--${name}`);
+            if (err)
+                return err;
+            i += 1;
+            continue;
+        }
+        if (tok.startsWith('-') && tok.length > 1) {
+            // Short option cluster. Each char might consume the rest of the token
+            // (or the next argv) as its value.
+            let k = 1;
+            while (k < tok.length) {
+                const letter = tok[k];
+                if (!SHORT_WITH_ARG.has(letter) && !SHORT_NO_ARG.has(letter)) {
+                    return {
+                        kind: 'invalid-option',
+                        message: `invalid option -- ${letter}`,
+                    };
+                }
+                if (SHORT_WITH_ARG.has(letter)) {
+                    // Consume the rest of this token as the value if anything remains,
+                    // otherwise pull from the next argv.
+                    const remainder = tok.slice(k + 1);
+                    const value = remainder.length > 0 ? remainder : undefined;
+                    const err = applyShort(letter, value, letter);
+                    if (err)
+                        return err;
+                    k = tok.length; // Consumed the rest.
+                    break;
+                }
+                const err = applyShort(letter, undefined, letter);
+                if (err)
+                    return err;
+                k += 1;
+            }
+            i += 1;
+            continue;
+        }
+        // Positional.
+        args.positional.push(tok);
+        i += 1;
+    }
+    // Upstream consumes only DBNAME and USERNAME from positionals; extras are
+    // warned about and ignored. We surface them all on `positional` so the
+    // caller can warn/log; applyStartupArgs takes care of the first two.
+    return {
+        ...args,
+        actions,
+        variables,
+        pset,
+    };
+};
+export const applyStartupArgs = (args, settings, baseConnectOpts, resolution) => {
+    // -------- 0) Constant client-version vars. -----------------------------
+    // Seed VERSION / VERSION_NAME / VERSION_NUM once (upstream seeds these from
+    // its compiled-in PG_VERSION before reading psqlrc / CLI vars). Done before
+    // the `-v` loop so a user-supplied `-v VERSION=…` still wins.
+    setStartupVars(settings.vars, CLIENT_VERSION);
+    // -------- 1) Variable assignments. -------------------------------------
+    for (const v of args.variables) {
+        if (v.value === '') {
+            // Mirror upstream `-v NAME` (no `=`): DeleteVariable.
+            settings.vars.unset(v.name);
+        }
+        else {
+            settings.vars.set(v.name, v.value);
+        }
+    }
+    // -------- 2) Settings flags. -------------------------------------------
+    if (args.echoAll)
+        settings.vars.set('ECHO', 'all');
+    if (args.echoErrors)
+        settings.vars.set('ECHO', 'errors');
+    if (args.echoQueries)
+        settings.vars.set('ECHO', 'queries');
+    if (args.echoHidden !== 'off') {
+        settings.echoHidden = args.echoHidden;
+        settings.vars.set('ECHO_HIDDEN', args.echoHidden === 'noexec' ? 'noexec' : 'on');
+    }
+    if (args.quiet) {
+        settings.quiet = true;
+        settings.vars.set('QUIET', 'on');
+    }
+    if (args.singleline) {
+        settings.singleline = true;
+        settings.vars.set('SINGLELINE', 'on');
+    }
+    if (args.singlestep) {
+        settings.singlestep = true;
+        settings.vars.set('SINGLESTEP', 'on');
+    }
+    if (args.onErrorStop) {
+        settings.onErrorStop = true;
+        settings.vars.set('ON_ERROR_STOP', 'on');
+    }
+    // -------- 3) Output formatting. ----------------------------------------
+    if (args.noAlign) {
+        settings.popt.topt.format = 'unaligned';
+    }
+    if (args.htmlMode) {
+        settings.popt.topt.format = 'html';
+    }
+    if (args.csvOutput) {
+        settings.popt.topt.format = 'csv';
+    }
+    if (args.tuplesOnly) {
+        settings.popt.topt.tuplesOnly = true;
+    }
+    if (args.expanded) {
+        settings.popt.topt.expanded = 'on';
+    }
+    if (args.fieldSepZero) {
+        settings.popt.topt.fieldSep = '\0';
+    }
+    else if (args.fieldSep !== undefined) {
+        settings.popt.topt.fieldSep = args.fieldSep;
+    }
+    if (args.recordSepZero) {
+        settings.popt.topt.recordSep = '\0';
+    }
+    else if (args.recordSep !== undefined) {
+        settings.popt.topt.recordSep = args.recordSep;
+    }
+    if (args.noPager) {
+        settings.popt.topt.pager = 'off';
+    }
+    // -------- 4) pset directives. ------------------------------------------
+    // We don't have a parsed `do_pset` here yet (lives in command/cmd_format),
+    // so we surface them as raw strings and let the integration layer feed
+    // them through once parsed. For tableattr (the most common -T use), apply
+    // directly.
+    for (const directive of args.pset) {
+        const eq = directive.indexOf('=');
+        if (eq >= 0) {
+            const key = directive.slice(0, eq);
+            const val = directive.slice(eq + 1);
+            if (key === 'tableattr' || key === 'T') {
+                settings.popt.topt.tableAttr = val.length > 0 ? val : null;
+            }
+            else if (key === 'pager') {
+                if (val === 'on' || val === 'off' || val === 'always') {
+                    settings.popt.topt.pager = val;
+                }
+            }
+            // Other directives left to the broader -P plumbing.
+        }
+    }
+    // -------- 5) Connection overrides. -------------------------------------
+    // Positional args follow upstream: positional[0] → dbname, positional[1] →
+    // username (if not already set by a flag).
+    let dbname = args.database;
+    let username = args.user;
+    if (args.positional[0] && !dbname)
+        dbname = args.positional[0];
+    if (args.positional[1] && !username)
+        username = args.positional[1];
+    // The argv flag layer mirrors the highest-priority CLI inputs (`-h`/`-p`
+    // / positional DBNAME / etc). Only populated entries end up in the layer
+    // so they don't accidentally clobber URI/env values.
+    // Seed with the full `-d` partial (carries ssl*/channelBinding/hostaddr/
+    // requireAuth — review #6), then overlay the explicit flag/positional
+    // values so `-h`/`-p`/`-U`/`-W`/positional still take precedence over `-d`.
+    const argvLayer = { ...(args.dashD ?? {}) };
+    if (args.host !== undefined)
+        argvLayer.host = args.host;
+    if (args.port !== undefined)
+        argvLayer.port = args.port;
+    if (username !== undefined)
+        argvLayer.user = username;
+    if (dbname !== undefined)
+        argvLayer.database = dbname;
+    if (args.password !== undefined)
+        argvLayer.password = args.password;
+    if (args.replication !== undefined)
+        argvLayer.replication = args.replication;
+    // Two modes:
+    //  - LEGACY: no `resolution` provided → behave exactly like before, with
+    //    `baseConnectOpts` supplying every default and argv overriding it.
+    //  - LAYERED: `resolution` provided → run the full vanilla-psql chain.
+    let connect;
+    if (resolution === undefined) {
+        const base = baseConnectOpts ?? {
+            host: 'localhost',
+            port: 5432,
+            user: '',
+            database: '',
+            ssl: 'prefer',
+        };
+        connect = { ...base, ...argvLayer };
+    }
+    else {
+        connect = resolveLayeredConnect(argvLayer, resolution, baseConnectOpts);
+    }
+    return { connect, preActions: args.actions };
+};
+/**
+ * Run the layered connection-parameter merge.
+ *
+ *   argv > URI partial > PG* env > .pgpass (password only) > service > libpq defaults
+ *
+ * `baseConnectOpts` (the legacy `ConnectOptions` argument) is treated as a
+ * pre-baked URI partial when the resolution path is used WITHOUT an explicit
+ * `uriPartial`. This keeps the door open for callers that still want to
+ * pass a fully-defaulted URI shape from `parseConnectionUri`.
+ */
+const resolveLayeredConnect = (argvLayer, resolution, legacyBase) => {
+    const env = resolution.env ?? {};
+    const uriPartial = resolution.uriPartial ??
+        (legacyBase !== undefined ? legacyBase : {});
+    // Pick the service entry: explicit `serviceName` argument first, else fall
+    // back to `$PGSERVICE`. The URI parser threads `?service=` through to its
+    // caller via this same field, so callers should populate `serviceName`
+    // from there before invoking us.
+    const serviceName = resolution.serviceName ?? env.PGSERVICE;
+    let serviceEntry;
+    if (serviceName !== undefined && serviceName !== '') {
+        serviceEntry = resolution.services?.get(serviceName);
+        if (serviceEntry === undefined) {
+            // Mirror libpq: if the user explicitly named a service (via
+            // `?service=`, conninfo `service=`, or `$PGSERVICE`) and it isn't
+            // found in any loaded service file, fail fast with the exact
+            // upstream wording. Without this the empty service layer would
+            // silently degrade to a different connection target — surprising
+            // and very hard to debug.
+            throw new Error(`definition of service "${serviceName}" not found`);
+        }
+    }
+    const serviceLayer = serviceEntry !== undefined
+        ? serviceEntryToConnectOptions(serviceEntry)
+        : {};
+    // Build the layer stack (highest priority first).
+    const envLayer = envConnectionDefaults(env);
+    const defaults = libpqConnectionDefaults(env);
+    const layers = [
+        argvLayer,
+        uriPartial,
+        envLayer,
+        serviceLayer,
+    ];
+    // First-pass merge (without pgpass) so we know what host/port/db/user
+    // ended up as. pgpass is a password-only layer that depends on the
+    // resolved target.
+    let merged = mergeConnectOptions(layers, defaults);
+    if (merged.password === undefined) {
+        const pgpassPwd = lookupPgPass(resolution.pgpassEntries ?? [], {
+            host: merged.host,
+            port: merged.port,
+            database: merged.database !== '' ? merged.database : merged.user,
+            user: merged.user,
+        });
+        if (pgpassPwd !== undefined) {
+            // Re-merge with pgpass slotted in just above libpq defaults so any
+            // explicit `password=` in env / service still wins.
+            const pgpassLayer = { password: pgpassPwd };
+            merged = mergeConnectOptions([...layers, pgpassLayer], defaults);
+        }
+    }
+    return merged;
+};
+// ---------------------------------------------------------------------------
+// Error-formatting helper for the integration layer.
+// ---------------------------------------------------------------------------
+export const formatParseError = (err) => err.message;