pg-admin-mcp 0.0.0-stage → 0.1.0

package/dist/core/policy.js

@@ -0,0 +1,98 @@
+import { CAPABILITY_ENV_SUFFIX, } from '../config/profiles.js';
+import { PgMcpError, envPrefix } from './errors.js';
+import { logger } from './logger.js';
+/** The shape `docs/design.md` names for `core/policy.ts` — capabilities plus the environment class, in one object. */
+export function resolveCapabilities(profile) {
+    return { ...profile.capabilities, envClass: profile.envClass };
+}
+/**
+ * `backup`/`restore` share `POLICY_ADMIN_DENIED`: the taxonomy in
+ * `core/errors.ts` has no dedicated code for them, and inventing one here would
+ * put a code in flight that no other module knows. The hint still names the
+ * exact variable, which is the part a caller acts on.
+ */
+const POLICY_DENIED_CODE = {
+    write: 'POLICY_READ_ONLY',
+    ddl: 'POLICY_DDL_DENIED',
+    admin: 'POLICY_ADMIN_DENIED',
+    explainAnalyze: 'POLICY_ANALYZE_DENIED',
+    backup: 'POLICY_ADMIN_DENIED',
+    restore: 'POLICY_ADMIN_DENIED',
+};
+const CAPABILITY_LABEL = {
+    write: 'writes (INSERT / UPDATE / DELETE)',
+    ddl: 'DDL (CREATE / ALTER / DROP)',
+    admin: 'administrative operations',
+    explainAnalyze: 'EXPLAIN ANALYZE, which executes the statement',
+    backup: 'pg_dump backups',
+    restore: 'pg_restore restores',
+};
+/** The exact env var that grants `capability` on `profile`. Exported for tests and for tool descriptions. */
+export function capabilityEnvVar(capability, alias) {
+    return `${envPrefix(alias)}_${CAPABILITY_ENV_SUFFIX[capability]}`;
+}
+/** Throws `POLICY_*` naming the exact env var when `profile` lacks `capability`. */
+export function requireCapability(capability, profile) {
+    if (profile.capabilities[capability])
+        return;
+    const envVar = capabilityEnvVar(capability, profile.alias);
+    throw new PgMcpError({
+        code: POLICY_DENIED_CODE[capability],
+        message: `profile "${profile.alias}" (envClass ${profile.envClass}) does not permit ${CAPABILITY_LABEL[capability]}`,
+        hint: `set ${envVar}=true for this profile and restart the server, then re-run`,
+        details: { profile: profile.alias, capability, envVar, envClass: profile.envClass },
+    });
+}
+/**
+ * The escalation matrix.
+ *
+ * **`production`** — `expect` mandatory including `keyChecksum`, `allowRowDrift`
+ * forced to 0. design.md is explicit about this row.
+ *
+ * **`development`** — a bare `confirm: true` commits. A dev database is the one
+ * place where the cost of a mistake is a re-seed, and making the guard
+ * expensive there is how it gets routed around in production.
+ *
+ * **`staging`** — `expect` mandatory, `keyChecksum` optional, `allowRowDrift`
+ * uncapped. The reasoning, since design.md leaves this row to us:
+ *
+ * - Requiring `expect` costs nothing an agent is not already doing in
+ *   production and buys the thing staging exists for — the *procedure* is
+ *   rehearsed identically. If the two-call flow is first exercised against
+ *   production, staging tested the wrong thing.
+ * - Requiring `keyChecksum` is where staging must diverge. Staging data is
+ *   rewritten by fixture loads, nightly refreshes and other agents' tests, so a
+ *   mandatory identity check fails routinely for reasons that have nothing to
+ *   do with the change under test — and a guard that cries wolf is a guard
+ *   someone disables. It stays available and is honoured whenever supplied;
+ *   it is simply not a precondition.
+ * - Same reasoning for the drift ceiling: on a churning database, forcing
+ *   `allowRowDrift = 0` would make every legitimate call a coin flip.
+ *
+ * Net: staging proves the *workflow*, production proves the *rows*.
+ */
+const CONFIRM_POLICY = {
+    development: { requireExpect: false, requireKeyChecksum: false, maxRowDrift: undefined },
+    staging: { requireExpect: true, requireKeyChecksum: false, maxRowDrift: undefined },
+    production: { requireExpect: true, requireKeyChecksum: true, maxRowDrift: 0 },
+};
+export function confirmPolicyFor(envClass) {
+    return { envClass, ...CONFIRM_POLICY[envClass] };
+}
+/**
+ * The drift tolerance that actually applies: the caller's request, floored at 0
+ * and clamped to the policy ceiling.
+ *
+ * A clamp is logged rather than silently applied — a caller who asked for
+ * `allowRowDrift: 5` on a production profile got 0, and finding that out from a
+ * `GUARD_ROW_DRIFT` alone would look like a bug in the guard.
+ */
+export function effectiveRowDrift(policy, requested, alias) {
+    const asked = requested === undefined || !Number.isFinite(requested) ? 0 : Math.max(0, Math.trunc(requested));
+    if (policy.maxRowDrift === undefined || asked <= policy.maxRowDrift)
+        return asked;
+    logger.warn(`profile "${alias}" is envClass ${policy.envClass}: allowRowDrift ${asked} clamped to ${policy.maxRowDrift} — ` +
+        'the row count must match the dry run exactly');
+    return policy.maxRowDrift;
+}
+//# sourceMappingURL=policy.js.map

package/dist/core/policy.js.map

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

package/dist/core/shutdown.js

@@ -0,0 +1,10 @@
+const hooks = [];
+export function onShutdown(hook) {
+    hooks.push(hook);
+}
+/** Runs every hook; one failing hook must not block the others. */
+export async function runShutdownHooks() {
+    const pending = hooks.splice(0, hooks.length);
+    await Promise.allSettled(pending.map(async (hook) => hook()));
+}
+//# sourceMappingURL=shutdown.js.map

package/dist/core/shutdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown.js","sourceRoot":"","sources":["../../src/core/shutdown.ts"],"names":[],"mappings":"AAQA,MAAM,KAAK,GAAmB,EAAE,CAAC;AAEjC,MAAM,UAAU,UAAU,CAAC,IAAkB;IAC3C,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACnB,CAAC;AAED,mEAAmE;AACnE,MAAM,CAAC,KAAK,UAAU,gBAAgB;IACpC,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC9C,MAAM,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;AAChE,CAAC"}

package/dist/core/stdout-guard.js

@@ -0,0 +1,25 @@
+/**
+ * stdout belongs to the JSON-RPC frame stream. Nothing else may write there.
+ *
+ * This module exists — instead of three statements at the top of `index.ts` —
+ * because ESM hoists imports: every static import of `index.ts` is evaluated
+ * *before* the first statement in its body runs. A dependency that logs at
+ * module-evaluation time would therefore beat an inline guard. Importing this
+ * file first makes the guard the first code the process executes.
+ *
+ * It redirects every console method that defaults to stdout: `log`/`info`/
+ * `debug` write via `kWriteToConsole(kUseStdout, …)` indirectly through
+ * `this.log`, and so do `table`/`group`/`count`/`timeEnd` — but `dir` and
+ * `dirxml` call `kWriteToConsole(kUseStdout, …)` directly, bypassing `log`,
+ * so they need their own redirect. A dependency that calls
+ * `process.stdout.write` directly still bypasses all of this; that is
+ * deliberate — patching `process.stdout.write` would also break the
+ * transport itself.
+ */
+console.log = console.error.bind(console);
+console.info = console.error.bind(console);
+console.debug = console.error.bind(console);
+console.dir = console.error.bind(console);
+console.dirxml = console.error.bind(console);
+export {};
+//# sourceMappingURL=stdout-guard.js.map

package/dist/core/stdout-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdout-guard.js","sourceRoot":"","sources":["../../src/core/stdout-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,CAAC,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AAC1C,OAAO,CAAC,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AAC3C,OAAO,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AAC5C,OAAO,CAAC,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AAC1C,OAAO,CAAC,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AAE7C,OAAO,EAAE,CAAC"}