pg-admin-mcp 0.0.0-stage → 0.1.0

package/dist/resources/index.js

@@ -0,0 +1,88 @@
+import { ProtocolError, ProtocolErrorCode, ResourceTemplate } from '@modelcontextprotocol/server';
+import { loadProfiles } from '../config/profiles.js';
+import { fromPgError, PgMcpError } from '../core/errors.js';
+import { assertSchemaAllowed, resolveRelation } from '../core/identifiers.js';
+import { listSchemas } from '../db/catalog.js';
+import { withSession } from '../db/session.js';
+import { gatherObjects } from '../tools/_object_kinds.js';
+import { buildRelationDetail } from '../tools/_relation_detail.js';
+/**
+ * Three read-only resources over the same `db/catalog.ts` listings the tools
+ * already use — no new catalog SQL.
+ *
+ * **Resources throw, tools return.** A tool handler's throw is swallowed by
+ * the SDK's `tools/call` seam and rewritten to `{ isError: true }` (see
+ * `core/errors.ts`'s file header and `toToolResult` — that is why every tool
+ * ends in `catch (err) { return toToolResult(err); }`). A resource handler
+ * has no such seam: `resources/read` propagates a thrown `ProtocolError`
+ * straight onto the wire as a real JSON-RPC error response. So the error path
+ * here is the exact opposite of a tool's — `throwResourceError` always
+ * throws, it never returns a result — and it must not be "fixed" to look like
+ * `toToolResult`.
+ */
+function throwResourceError(err) {
+    const pgErr = err instanceof PgMcpError ? err : fromPgError(err);
+    const code = pgErr.code === 'PROFILE_UNKNOWN' || pgErr.code === 'IDENTIFIER_UNKNOWN' ? ProtocolErrorCode.InvalidParams : ProtocolErrorCode.InternalError;
+    throw new ProtocolError(code, pgErr.toString(), { code: pgErr.code, hint: pgErr.hint, details: pgErr.details });
+}
+/** A URI-template variable is a `string | string[]` per the SDK; ours are always single path segments. Malformed/missing -> InvalidParams. */
+export function requireVariable(variables, name) {
+    const value = variables[name];
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new ProtocolError(ProtocolErrorCode.InvalidParams, `resource URI is missing a "${name}" segment`);
+    }
+    return value;
+}
+function jsonContents(uri, data) {
+    return { contents: [{ uri: uri.href, text: JSON.stringify(data, null, 2), mimeType: 'application/json' }] };
+}
+/** `postgres://<profile>/schemas` — every schema in scope for the profile. */
+export async function readSchemasResource(uri, variables) {
+    try {
+        const profileAlias = requireVariable(variables, 'profile');
+        const registry = loadProfiles();
+        const profile = registry.get(profileAlias);
+        const schemas = await withSession(profile, (client) => listSchemas(client, profile.schemas), { operation: 'resource:schemas' });
+        return jsonContents(uri, { profile: profile.alias, schemas });
+    }
+    catch (err) {
+        return throwResourceError(err);
+    }
+}
+/** `postgres://<profile>/schema/<schema>` — every object in one schema. */
+export async function readSchemaResource(uri, variables) {
+    try {
+        const profileAlias = requireVariable(variables, 'profile');
+        const schema = requireVariable(variables, 'schema');
+        const registry = loadProfiles();
+        const profile = registry.get(profileAlias);
+        assertSchemaAllowed(profile, schema);
+        const objects = await withSession(profile, (client) => gatherObjects(client, [schema]), { operation: 'resource:schema' });
+        return jsonContents(uri, { profile: profile.alias, schema, objects });
+    }
+    catch (err) {
+        return throwResourceError(err);
+    }
+}
+/** `postgres://<profile>/table/<schema>/<table>` — full detail for one table-like relation. */
+export async function readTableResource(uri, variables) {
+    try {
+        const profileAlias = requireVariable(variables, 'profile');
+        const schema = requireVariable(variables, 'schema');
+        const table = requireVariable(variables, 'table');
+        const registry = loadProfiles();
+        const profile = registry.get(profileAlias);
+        const rel = await resolveRelation(profile, schema, table);
+        const detail = await withSession(profile, (client) => buildRelationDetail(client, rel), { operation: 'resource:table' });
+        return jsonContents(uri, { profile: profile.alias, schema, table, kind: rel.kind, detail });
+    }
+    catch (err) {
+        return throwResourceError(err);
+    }
+}
+export function registerResources(server) {
+    server.registerResource('schemas', new ResourceTemplate('postgres://{profile}/schemas', { list: undefined }), { title: 'Schemas in scope for a profile', mimeType: 'application/json' }, readSchemasResource);
+    server.registerResource('schema', new ResourceTemplate('postgres://{profile}/schema/{schema}', { list: undefined }), { title: 'Objects in one schema', mimeType: 'application/json' }, readSchemaResource);
+    server.registerResource('table', new ResourceTemplate('postgres://{profile}/table/{schema}/{table}', { list: undefined }), { title: 'Full detail for one table-like relation', mimeType: 'application/json' }, readTableResource);
+}
+//# sourceMappingURL=index.js.map

package/dist/resources/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/resources/index.ts"],"names":[],"mappings":"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"}

package/dist/runtime/binaries.js

@@ -0,0 +1,356 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import process from 'node:process';
+import { PgMcpError } from '../core/errors.js';
+import { logger } from '../core/logger.js';
+import { onShutdown } from '../core/shutdown.js';
+/**
+ * Locating, versioning and running the PostgreSQL client binaries —
+ * `pg_dump`, `pg_restore`, `psql`. The only module in this project that
+ * spawns a child process.
+ *
+ * **Lazy, never at startup.** The server must boot and serve the other 16
+ * tools on a machine where no client binary exists at all — `pnpm dev` on a
+ * laptop, a container built without the PGDG packages. Nothing here runs until
+ * a tool actually needs a binary; {@link requireBinary} is what fails, at the
+ * tool boundary, with `BINARY_MISSING` naming the binary it could not find and
+ * the image that ships it. Resolution is cached per resolved command path, so
+ * the `--version` probe costs one spawn per process, not one per call.
+ *
+ * **Spawn discipline — argv arrays, never a shell.** Every child is spawned
+ * with an argv array and `shell: false` (Node's default), so nothing in an
+ * operator-supplied path, schema name or table pattern can be a shell
+ * metacharacter. Every option is passed in `--opt=value` form rather than as
+ * two argv entries, so a value that begins with `-` is a value, not a flag.
+ *
+ * **The password goes on the child's `env` as `PGPASSWORD`, never in argv.**
+ * argv is world-readable through `ps` on every platform this server runs on;
+ * `/proc/<pid>/environ` is not (it is readable only by the process owner and
+ * root). `Profile.password()` is a closure — the secret is never an enumerable
+ * property of the profile — and this module is the only other caller of it
+ * besides `db/pool.ts`. {@link buildSpawnEnv} is the one place that reads it,
+ * and `test/unit/binaries.test.ts` asserts the sentinel appears in no argv
+ * entry of any command this module builds.
+ *
+ * **Nothing may reach stdout.** stdout is the MCP transport. A child is always
+ * spawned with `stdio: ['ignore', 'pipe', 'pipe']` — never `'inherit'`, which
+ * would splice `pg_dump`'s output straight into the JSON-RPC frame stream.
+ * `pg_dump` writes its archive through its own `--file=`, and the only stdout
+ * this module ever reads is `pg_restore --list`'s table of contents, captured
+ * into a capped buffer.
+ *
+ * **Child hygiene.** Every child gets a timeout and is killed when it fires; a
+ * `pg_dump` left running holds a server connection open. Live children are
+ * tracked and killed by a `core/shutdown.ts#onShutdown` hook, so a container
+ * stop does not orphan one.
+ */
+export const PG_BINARIES = ['pg_dump', 'pg_restore', 'psql'];
+/** The image tag suggestion every `BINARY_MISSING` hint ends with. */
+const IMAGE_HINT = 'the published image ships pg_dump/pg_restore/psql — run pg-admin-mcp:pg<major> (e.g. pg-admin-mcp:pg17), or install ' +
+    'postgresql-client and point PG_MCP_PG_BIN_DIR at the directory containing them';
+/**
+ * `PG_MCP_PG_BIN_DIR` first, `PATH` second — exactly the design.md contract.
+ * A configured directory wins outright rather than being appended to `PATH`:
+ * an operator who set it did so to pin a specific client major, and silently
+ * falling back to a different one on `PATH` is how a version mismatch becomes
+ * a mystery.
+ */
+export function binaryCommand(name, env = process.env) {
+    const dir = env['PG_MCP_PG_BIN_DIR']?.trim();
+    return dir === undefined || dir === '' ? name : path.join(dir, name);
+}
+/** `pg_dump (PostgreSQL) 17.5 (Debian …)` -> `17`. Also copes with `18beta1` and with a bare `17.5`. */
+export function parseMajor(versionLine) {
+    const qualified = /\(PostgreSQL\)\s+(\d+)/.exec(versionLine);
+    const bare = qualified ?? /(\d+)/.exec(versionLine);
+    const major = bare?.[1];
+    return major === undefined ? undefined : Number.parseInt(major, 10);
+}
+/** `170005` -> `17`. PostgreSQL's `server_version_num` is `major * 10000 + minor` for every version this server supports. */
+export function serverMajorFromNum(serverVersionNum) {
+    return Math.trunc(serverVersionNum / 10000);
+}
+function binaryMissing(name, command, cause) {
+    return new PgMcpError({
+        code: 'BINARY_MISSING',
+        message: `${name} was not found (tried "${command}")`,
+        hint: IMAGE_HINT,
+        details: { binary: name, command },
+        cause,
+    });
+}
+// ---------------------------------------------------------------------------
+// Child process plumbing
+// ---------------------------------------------------------------------------
+const live = new Set();
+/** SIGTERM first so `pg_dump` can close its connection; SIGKILL if it is still there after this. */
+const KILL_GRACE_MS = 5000;
+function killChild(child) {
+    if (child.exitCode !== null || child.signalCode !== null)
+        return;
+    child.kill('SIGTERM');
+    const hard = setTimeout(() => {
+        if (child.exitCode === null && child.signalCode === null)
+            child.kill('SIGKILL');
+    }, KILL_GRACE_MS);
+    // Never let the grace timer hold the event loop open on its own.
+    hard.unref();
+}
+// A pg_dump still running when the container stops holds a server connection.
+onShutdown(() => {
+    for (const child of live) {
+        logger.warn(`killing a still-running client binary (pid ${child.pid ?? -1}) during shutdown`);
+        killChild(child);
+    }
+});
+const DEFAULT_STDOUT_MAX_BYTES = 8 * 1024 * 1024;
+/** Enough stderr to diagnose; a `pg_restore` that fails on every one of 10 000 objects must not build a 10 MB error message. */
+const STDERR_MAX_BYTES = 64 * 1024;
+/**
+ * The child's environment. **The only place `Profile.password()` is read in
+ * this module**, and it lands on `PGPASSWORD` — never on argv.
+ */
+export function buildSpawnEnv(password, base = process.env) {
+    if (password === undefined)
+        return { ...base };
+    return { ...base, PGPASSWORD: password };
+}
+function clip(text, max) {
+    return text.length <= max ? text : `${text.slice(0, max)}…[truncated]`;
+}
+/** The last few lines of stderr — what a human actually needs, without the progress noise above it. */
+function stderrTail(stderr, lines = 6) {
+    const kept = stderr.trimEnd().split('\n').slice(-lines).join('\n').trim();
+    return kept === '' ? '(no stderr output)' : kept;
+}
+/**
+ * Spawns one client binary and waits for it. Resolves with the captured
+ * streams on exit code 0; throws `PgMcpError` otherwise — `BINARY_MISSING` for
+ * an `ENOENT`, `TIMEOUT` for a child killed by the deadline, and `PG_ERROR`
+ * carrying the stderr tail for anything else. The raw stderr never surfaces
+ * unexplained: every message says which binary, which operation, and what to
+ * do next.
+ */
+export async function runBinary(name, command, args, opts) {
+    const child = spawn(command, [...args], {
+        // Never 'inherit' on stdout — that is the MCP transport. stdin is closed
+        // so a client binary that wants to prompt for a password fails fast
+        // instead of hanging forever on a tty that is not there.
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: buildSpawnEnv(opts.password),
+        shell: false,
+        windowsHide: true,
+    });
+    live.add(child);
+    const stdoutMax = opts.stdoutMaxBytes ?? DEFAULT_STDOUT_MAX_BYTES;
+    let stdout = '';
+    let stderr = '';
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (chunk) => {
+        if (stderr.length < STDERR_MAX_BYTES)
+            stderr += chunk;
+    });
+    if (opts.sink === undefined) {
+        child.stdout.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => {
+            if (stdout.length < stdoutMax)
+                stdout += chunk;
+        });
+    }
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        killChild(child);
+    }, opts.timeoutMs);
+    try {
+        const exited = new Promise((resolve) => {
+            child.once('error', resolve);
+            child.once('close', (code, signal) => resolve({ code, signal }));
+        });
+        // The sink is awaited BEFORE the exit is inspected: a destination write
+        // that failed is the real diagnosis, and a child still filling a pipe
+        // nobody drains would otherwise block forever.
+        if (opts.sink !== undefined) {
+            try {
+                await opts.sink(child.stdout);
+            }
+            catch (err) {
+                killChild(child);
+                await exited;
+                throw err;
+            }
+        }
+        const outcome = await exited;
+        if (outcome instanceof Error) {
+            if (outcome.code === 'ENOENT')
+                throw binaryMissing(name, command, outcome);
+            throw new PgMcpError({
+                code: 'PG_ERROR',
+                message: `${name} could not be started for ${opts.operation}: ${outcome.message}`,
+                hint: `check that "${command}" is executable by this process — ${IMAGE_HINT}`,
+                details: { binary: name, command, operation: opts.operation },
+                cause: outcome,
+            });
+        }
+        if (timedOut) {
+            throw new PgMcpError({
+                code: 'TIMEOUT',
+                message: `${name} exceeded the ${opts.timeoutMs} ms limit for ${opts.operation} and was killed`,
+                hint: 'raise timeoutMs on this call (bounded by PG_<ALIAS>_EXPORT_TIMEOUT_MAX_MS), narrow the scope, or run the ' +
+                    'dump closer to the server — the child was terminated and left nothing behind',
+                details: { binary: name, operation: opts.operation, timeoutMs: opts.timeoutMs },
+            });
+        }
+        if (outcome.code !== 0) {
+            throw new PgMcpError({
+                code: 'PG_ERROR',
+                message: `${name} failed during ${opts.operation} (exit ${outcome.code ?? `signal ${outcome.signal ?? 'unknown'}`}): ` +
+                    stderrTail(stderr),
+                hint: 'fix the condition reported above and re-run — this is the client binary\'s own diagnosis, not a server refusal',
+                details: {
+                    binary: name,
+                    operation: opts.operation,
+                    exitCode: outcome.code,
+                    signal: outcome.signal,
+                    stderr: clip(stderr, STDERR_MAX_BYTES),
+                },
+            });
+        }
+        return { stdout, stderr };
+    }
+    finally {
+        clearTimeout(timer);
+        live.delete(child);
+    }
+}
+// ---------------------------------------------------------------------------
+// Resolution + version cache
+// ---------------------------------------------------------------------------
+const cache = new Map();
+/** Test seam — the cache is keyed by resolved command, so a test that changes `PG_MCP_PG_BIN_DIR` needs this. */
+export function resetBinaryCache() {
+    cache.clear();
+}
+async function probe(name, command) {
+    const { stdout } = await runBinary(name, command, ['--version'], {
+        timeoutMs: 10_000,
+        operation: `${name} --version`,
+        stdoutMaxBytes: 4096,
+    });
+    const version = stdout.trim().split('\n')[0]?.trim() ?? '';
+    const major = parseMajor(version);
+    if (major === undefined) {
+        throw new PgMcpError({
+            code: 'BINARY_MISSING',
+            message: `"${command}" answered --version with something unparseable: ${JSON.stringify(clip(version, 200))}`,
+            hint: `that is not a PostgreSQL client binary — ${IMAGE_HINT}`,
+            details: { binary: name, command },
+        });
+    }
+    return { name, command, version, major };
+}
+/**
+ * Resolves one binary and its version, once per process. Everything that needs
+ * a client binary goes through here, so `BINARY_MISSING` is raised at the tool
+ * boundary and never at import time.
+ *
+ * A failed probe is **not** cached: an operator who installs the package (or
+ * fixes `PG_MCP_PG_BIN_DIR`) while the server is running gets a working tool on
+ * the next call rather than a refusal frozen in for the process lifetime.
+ */
+export async function requireBinary(name, env = process.env) {
+    const command = binaryCommand(name, env);
+    const key = `${name}${command}`;
+    const cached = cache.get(key);
+    if (cached !== undefined)
+        return cached;
+    const pending = probe(name, command);
+    cache.set(key, pending);
+    try {
+        return await pending;
+    }
+    catch (err) {
+        cache.delete(key);
+        throw err;
+    }
+}
+/** {@link requireBinary} for several at once, resolved in parallel. */
+export async function requireBinaries(names, env = process.env) {
+    const resolved = await Promise.all(names.map(async (name) => requireBinary(name, env)));
+    return Object.fromEntries(resolved.map((bin) => [bin.name, bin]));
+}
+// ---------------------------------------------------------------------------
+// Version compatibility (design.md risk 2 and risk 10)
+// ---------------------------------------------------------------------------
+/**
+ * design.md risk 2 — **a `pg_dump` older than the server refuses to run**, with
+ * a message about "server version mismatch" that says nothing about what to do.
+ * Caught here, at the tool boundary, before the child is spawned at all.
+ *
+ * The reverse (a newer client against an older server) is supported by
+ * PostgreSQL and is deliberately allowed.
+ *
+ * `BINARY_MISSING` is the code, not a new one: what is missing is a *usable*
+ * client for this server, and inventing a code here would put one in flight
+ * that no other module in the taxonomy knows.
+ */
+export function assertClientCoversServer(client, serverVersionNum, serverVersion, profileAlias) {
+    const serverMajor = serverMajorFromNum(serverVersionNum);
+    if (client.major >= serverMajor)
+        return;
+    throw new PgMcpError({
+        code: 'BINARY_MISSING',
+        message: `${client.name} ${client.major} is older than profile "${profileAlias}"'s server (PostgreSQL ${serverVersion}), ` +
+            'and PostgreSQL client binaries refuse to run against a newer server',
+        hint: `run the pg-admin-mcp:pg${serverMajor} image tag (or point PG_MCP_PG_BIN_DIR at a postgresql-client-${serverMajor} installation) and re-run`,
+        details: {
+            binary: client.name,
+            clientMajor: client.major,
+            serverMajor,
+            serverVersion,
+            profile: profileAlias,
+        },
+    });
+}
+/**
+ * design.md risk 10 — **archive format is forward-only.** `pg_dump 17` dumps a
+ * 16 server fine, but a custom-format archive produced by 17 cannot be read by
+ * `pg_restore 16`: the archive header carries a format version the older
+ * program does not know, and its own error ("unsupported version (1.16) in
+ * file header") names nothing an operator can act on.
+ */
+export function assertArchiveReadable(archiveMajor, restore, archivePath) {
+    if (archiveMajor <= restore.major)
+        return;
+    throw new PgMcpError({
+        code: 'BINARY_MISSING',
+        message: `"${archivePath}" was produced by pg_dump ${archiveMajor}, and the local pg_restore is ${restore.major} — ` +
+            'an archive can never be restored by an older pg_restore than the pg_dump that wrote it',
+        hint: `run the pg-admin-mcp:pg${archiveMajor} image tag (or point PG_MCP_PG_BIN_DIR at a postgresql-client-${archiveMajor} installation) and re-run`,
+        details: { archivePath, archiveMajor, restoreMajor: restore.major },
+    });
+}
+// ---------------------------------------------------------------------------
+// Connection arguments
+// ---------------------------------------------------------------------------
+/**
+ * The connection half of every client-binary argv.
+ *
+ * `--opt=value` form throughout, so a database or user name beginning with `-`
+ * is a value and not a flag. `--no-password` guarantees the child never blocks
+ * on a password prompt — stdin is closed anyway, but a client binary that
+ * decides to prompt would otherwise fail with a confusing EOF error instead of
+ * a clear "no password supplied".
+ *
+ * **No password appears here.** It reaches the child through
+ * {@link buildSpawnEnv} only.
+ */
+export function connectionArgs(profile) {
+    return [
+        `--host=${profile.host}`,
+        `--port=${profile.port}`,
+        `--username=${profile.user}`,
+        '--no-password',
+    ];
+}
+//# sourceMappingURL=binaries.js.map

package/dist/runtime/binaries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binaries.js","sourceRoot":"","sources":["../../src/runtime/binaries.ts"],"names":[],"mappings":"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"}

package/dist/runtime/env-file.js

@@ -0,0 +1,62 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { parseEnv } from 'node:util';
+import { readString } from '../config/env.js';
+import { PgMcpError } from '../core/errors.js';
+/**
+ * Optional `.env` file loading for host mode (`npx pg-admin-mcp`).
+ *
+ * In the container, Compose / `docker run --env-file` already turn a `.env`
+ * into real environment variables. A host run has no such launcher, and MCP
+ * client configs (`.mcp.json`) are usually committed — so secrets need a place
+ * that is not that file. `PG_MCP_ENV_FILE` names it.
+ *
+ * **The real environment wins.** A key already present in `env` — even as an
+ * empty string — is never overwritten by the file. That makes the committed
+ * client config authoritative for every key it sets, and the file a fallback
+ * for whatever it leaves out (typically just the `PG_<ALIAS>_URL` lines that
+ * carry passwords). Same precedence as Node's own `--env-file`.
+ *
+ * A relative path resolves against `cwd` — for an MCP client that is the
+ * directory the client was launched from, not wherever its config file lives.
+ *
+ * Parsing is `util.parseEnv` (Node >= 20.12): stdlib, the same dotenv dialect
+ * Node's `--env-file` understands, no new dependency.
+ *
+ * Mutates `env` in place rather than returning a copy because the rest of the
+ * server reads `process.env` lazily, per call (`loadProfiles()` runs inside each
+ * tool handler) — the merge has to land where those reads look. Tests inject a
+ * plain object instead, so they never touch the real `process.env`.
+ *
+ * @returns the absolute path that was loaded, or `undefined` when
+ *   `PG_MCP_ENV_FILE` is unset/blank (a no-op).
+ * @throws PgMcpError (`PROFILE_MISCONFIGURED`) when the file cannot be read.
+ *   Deliberately fatal: a named-but-missing secrets file would otherwise boot a
+ *   server whose every profile fails later with a far less obvious error.
+ */
+export function loadEnvFile(env = process.env, cwd = process.cwd()) {
+    const raw = readString(env, 'PG_MCP_ENV_FILE')?.trim();
+    if (raw === undefined || raw === '')
+        return undefined;
+    const file = path.resolve(cwd, raw);
+    let contents;
+    try {
+        contents = readFileSync(file, 'utf8');
+    }
+    catch (err) {
+        throw new PgMcpError({
+            code: 'PROFILE_MISCONFIGURED',
+            message: `PG_MCP_ENV_FILE points to ${file}, which could not be read`,
+            hint: 'create the file (e.g. copy .env.example to .env), fix the path, or unset PG_MCP_ENV_FILE — ' +
+                'a relative path resolves against the directory the MCP client was launched from',
+            cause: err,
+        });
+    }
+    for (const [key, value] of Object.entries(parseEnv(contents))) {
+        if (!Object.hasOwn(env, key))
+            env[key] = value;
+    }
+    return file;
+}
+//# sourceMappingURL=env-file.js.map

package/dist/runtime/env-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-file.js","sourceRoot":"","sources":["../../src/runtime/env-file.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,OAAO,MAAM,cAAc,CAAC;AACnC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,WAAW,CAAC,MAAyB,OAAO,CAAC,GAAG,EAAE,MAAc,OAAO,CAAC,GAAG,EAAE;IAC3F,MAAM,GAAG,GAAG,UAAU,CAAC,GAAG,EAAE,iBAAiB,CAAC,EAAE,IAAI,EAAE,CAAC;IACvD,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,EAAE;QAAE,OAAO,SAAS,CAAC;IAEtD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACpC,IAAI,QAAgB,CAAC;IACrB,IAAI,CAAC;QACH,QAAQ,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACxC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,UAAU,CAAC;YACnB,IAAI,EAAE,uBAAuB;YAC7B,OAAO,EAAE,6BAA6B,IAAI,2BAA2B;YACrE,IAAI,EACF,6FAA6F;gBAC7F,iFAAiF;YACnF,KAAK,EAAE,GAAG;SACX,CAAC,CAAC;IACL,CAAC;IAED,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC;QAC9D,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC;YAAE,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACjD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/runtime/environment.js

@@ -0,0 +1,34 @@
+import process from 'node:process';
+import { readPathList } from '../config/env.js';
+/**
+ * Runtime facts about the process. Env is read through an injectable seam so unit
+ * tests never mutate the real `process.env`.
+ */
+/**
+ * True when the server runs inside the published image.
+ *
+ * Reads `PG_MCP_IN_CONTAINER` (set to `1` by the Dockerfile) instead of probing
+ * `/.dockerenv`: deterministic, and unit-testable without a container.
+ */
+export function inContainer(env = process.env) {
+    const raw = env['PG_MCP_IN_CONTAINER'];
+    return raw === '1' || raw?.toLowerCase() === 'true';
+}
+/**
+ * First entry of `PG_MCP_ALLOWED_DIRS`, which is where relative file arguments
+ * resolve. Full allow-list parsing and symlink-escape checks belong to
+ * `core/paths.ts`; this is only the "where do files land by default" answer.
+ */
+export function workspaceRoot(env = process.env) {
+    const first = readPathList(env, 'PG_MCP_ALLOWED_DIRS')[0];
+    return first ?? (inContainer(env) ? '/workspace' : process.cwd());
+}
+export function runtimeReport(env = process.env) {
+    const major = Number.parseInt(env['PG_MCP_PG_MAJOR'] ?? '', 10);
+    return {
+        runtime: inContainer(env) ? 'container' : 'host',
+        node: process.versions.node,
+        ...(Number.isInteger(major) ? { pgMajor: major } : {}),
+    };
+}
+//# sourceMappingURL=environment.js.map

package/dist/runtime/environment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.js","sourceRoot":"","sources":["../../src/runtime/environment.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,cAAc,CAAC;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEhD;;;GAGG;AAEH;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC9D,MAAM,GAAG,GAAG,GAAG,CAAC,qBAAqB,CAAC,CAAC;IACvC,OAAO,GAAG,KAAK,GAAG,IAAI,GAAG,EAAE,WAAW,EAAE,KAAK,MAAM,CAAC;AACtD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,MAAyB,OAAO,CAAC,GAAG;IAChE,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,EAAE,qBAAqB,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1D,OAAO,KAAK,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;AACpE,CAAC;AASD,MAAM,UAAU,aAAa,CAAC,MAAyB,OAAO,CAAC,GAAG;IAChE,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,iBAAiB,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;IAChE,OAAO;QACL,OAAO,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM;QAChD,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,IAAI;QAC3B,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACvD,CAAC;AACJ,CAAC"}