pg-admin-mcp 0.0.0-stage → 0.1.0

package/dist/tools/insert_batch.js

@@ -0,0 +1,212 @@
+import { z } from 'zod';
+import { readInt } from '../config/env.js';
+import { loadProfiles } from '../config/profiles.js';
+import { toToolResult } from '../core/errors.js';
+import { formatOutcome } from '../core/format.js';
+import { CONFIRM_PROTOCOL_DESCRIPTION, runGuardedMutation } from '../core/guards.js';
+import { resolveColumn, resolveRelation } from '../core/identifiers.js';
+import { getColumns, getPrimaryKey } from '../db/catalog.js';
+import { withSession } from '../db/session.js';
+import { arrayCast, confirmFragment, toExpectToken } from './_batch_shared.js';
+import { scalarValue } from './select.js';
+import { defineTool, profileParam } from './_shared.js';
+/**
+ * `postgres_insert_batch` — bulk INSERT, still routed through
+ * `core/guards.ts#runGuardedMutation` for the dry-run/confirm protocol and the
+ * `write` capability check, even though there is no WHERE to guard.
+ *
+ * ## Two strategies, one guard path
+ *
+ * Below `PG_MCP_INSERT_BULK_THRESHOLD` rows: `INSERT … SELECT * FROM
+ * unnest($1::type[], $2::type[], …)` — one bound array parameter per column,
+ * catalog-typed via `db/catalog.ts#getColumns` (never guessed), one round
+ * trip for the whole batch.
+ *
+ * Above it: `INSERT … SELECT … FROM jsonb_to_recordset($1::jsonb) AS
+ * t(col1 type1, …)` — the whole batch collapses into ONE bound parameter
+ * instead of one array parameter per column, which avoids `node-postgres`'s
+ * per-element array-literal serialization pass (`arrayString`, string
+ * concatenation over every cell) becoming the bottleneck once a batch is wide
+ * (many columns) and long (many rows) at once.
+ *
+ * **Why not literal `COPY FROM STDIN` (design.md's original wording) above the
+ * threshold**, stated plainly because the deviation is deliberate, not an
+ * oversight: `runGuardedMutation` wraps the caller's `sql` as
+ * `WITH pg_admin_mcp_target AS (<sql> RETURNING …)`. `COPY` is a wire-protocol
+ * command, not a `RETURNING`-capable statement — it cannot appear inside that
+ * CTE, so it cannot be composed with the guard at all without reimplementing
+ * the guard's hash/row-count/checksum comparison for a second, COPY-shaped
+ * code path (`core/guards.ts`'s own header: compose the guard, do not
+ * reinvent it). Worse, `COPY` has no `RETURNING`, so a literal-COPY confirm
+ * could only compute a `keyChecksum` from the *input* rows rather than the
+ * rows actually written — silently unsafe on a table with a DB-generated
+ * primary key using `ON CONFLICT`-free semantics that differ from the
+ * unnest/jsonb path's, exactly the kind of hidden strategy-dependent safety
+ * hole this server's guard exists to avoid. `jsonb_to_recordset` keeps every
+ * safety property (RETURNING, checksum, ON CONFLICT support) byte-for-byte
+ * identical between both strategies.
+ *
+ * `ON CONFLICT DO NOTHING`/`DO UPDATE` are explicit opt-ins (`onConflict`);
+ * omitted, a conflicting row aborts the whole statement, as vanilla INSERT
+ * does. `DO NOTHING ... RETURNING` only returns the rows actually inserted,
+ * so the guard's row count/checksum reflect what was truly written either way.
+ */
+const MAX_ROWS = 20_000;
+const onConflictSchema = z
+    .object({
+    target: z
+        .array(z.string().min(1))
+        .min(1)
+        .optional()
+        .describe('Conflict target columns — must match a unique or exclusion constraint. Required by PostgreSQL when action is "update".'),
+    action: z.union([
+        z.literal('nothing'),
+        z.object({ update: z.array(z.string().min(1)).min(1).describe('Columns to overwrite from EXCLUDED on conflict.') }),
+    ]),
+})
+    .describe('Opt-in ON CONFLICT clause. Omit for a plain INSERT that errors on any conflict.');
+const inputSchema = z.object({
+    ...profileParam,
+    schema: z.string().min(1).describe('Schema name, e.g. "app".'),
+    table: z.string().min(1).describe('Table name within the schema.'),
+    columns: z.array(z.string().min(1)).min(1).describe('Column names, in the order every row supplies values.'),
+    rows: z
+        .array(z.record(z.string().min(1), scalarValue))
+        .min(1)
+        .max(MAX_ROWS)
+        .describe(`Rows to insert, each keyed by column name. A row missing one of "columns" binds NULL for it. Max ${MAX_ROWS} rows per call.`),
+    onConflict: onConflictSchema.optional(),
+    ...confirmFragment,
+});
+/**
+ * Pure SQL-building core of `insert_batch` — split out from the handler so
+ * the threshold switch and the catalog-typed cast list can be unit-tested
+ * without a live database (`resolveRelation`/`getColumns` need one; this
+ * doesn't, given already-resolved idents and a `dataTypeOf` lookup).
+ */
+export function buildInsertSql(schemaIdent, tableIdent, columnIdents, columns, rows, dataTypeOf, threshold) {
+    if (rows.length > threshold) {
+        const jsonRows = rows.map((row) => {
+            const obj = {};
+            for (const name of columns)
+                obj[name] = row[name] ?? null;
+            return obj;
+        });
+        const fieldDefs = columns.map((name, i) => `${columnIdents[i]} ${dataTypeOf(name)}`).join(', ');
+        const sql = `INSERT INTO ${schemaIdent}.${tableIdent} (${columnIdents.join(', ')}) ` +
+            `SELECT ${columnIdents.join(', ')} FROM jsonb_to_recordset($1::jsonb) AS t(${fieldDefs})`;
+        return { sql, params: [JSON.stringify(jsonRows)], strategy: 'jsonb' };
+    }
+    const unnestArgs = columns.map((name, i) => `$${i + 1}::${arrayCast(dataTypeOf(name))}`).join(', ');
+    const aliasCols = columns.map((_, i) => `c${i}`).join(', ');
+    const sql = `INSERT INTO ${schemaIdent}.${tableIdent} (${columnIdents.join(', ')}) ` +
+        `SELECT * FROM unnest(${unnestArgs}) AS t(${aliasCols})`;
+    const params = columns.map((name) => rows.map((row) => row[name] ?? null));
+    return { sql, params, strategy: 'unnest' };
+}
+function buildOnConflictSql(onConflict, schema, table, knownColumns) {
+    if (onConflict === undefined)
+        return '';
+    const targetIdents = (onConflict.target ?? []).map((name) => resolveColumn(schema, table, name, knownColumns));
+    const targetSql = targetIdents.length > 0 ? ` (${targetIdents.join(', ')})` : '';
+    if (onConflict.action === 'nothing')
+        return ` ON CONFLICT${targetSql} DO NOTHING`;
+    const setSql = onConflict.action.update
+        .map((name) => resolveColumn(schema, table, name, knownColumns))
+        .map((ident) => `${ident} = EXCLUDED.${ident}`)
+        .join(', ');
+    return ` ON CONFLICT${targetSql} DO UPDATE SET ${setSql}`;
+}
+export const insertBatchTool = defineTool('postgres_insert_batch', {
+    title: 'Bulk INSERT rows into a PostgreSQL table',
+    description: 'Bulk INSERT — set-based for ordinary volumes, switching internally to a single-parameter bulk strategy above ' +
+        'PG_MCP_INSERT_BULK_THRESHOLD rows (default 1000) to avoid per-column array-serialization overhead on very large ' +
+        'batches; both strategies produce identical rows and go through the same guard. Column casts come from the ' +
+        "table's real catalog types, never guessed. `onConflict` opts into DO NOTHING or DO UPDATE SET ... FROM EXCLUDED " +
+        `(omitted = plain INSERT, errors on any conflict). There is no WHERE to guard, but every call still goes ` +
+        `through the capability check and the dry-run/confirm protocol below. If the table's primary key is ` +
+        `server-generated (IDENTITY/SERIAL/DEFAULT nextval) and its column is omitted from \`columns\`, the confirm ` +
+        `step is verified by row count only, not by key checksum — a rolled-back dry run still advances the ` +
+        `sequence, so the confirm's real keys would never match a previewed checksum. That holds on production too: ` +
+        `an INSERT's affected rows are the rows in your own parameters, which the hash already pins, so this is the ` +
+        `one tool a production profile may confirm on row count alone (expect and the hash stay mandatory). Include ` +
+        `the key column with an explicit value in \`columns\`/\`rows\` if you want checksum-pinned confirmation ` +
+        `anyway. ${CONFIRM_PROTOCOL_DESCRIPTION}`,
+    inputSchema,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+}, async (args) => {
+    try {
+        const registry = loadProfiles();
+        const profile = registry.get(args.profile);
+        const rel = await resolveRelation(profile, args.schema, args.table);
+        // Catalog lookups run in their own session, sequentially BEFORE
+        // runGuardedMutation opens its own transaction — never a second
+        // checkout inside that transaction (see guards.ts's own doc comment).
+        const { columnByName, knownColumns, pkIdents, pkColumnNames } = await withSession(profile, async (client) => {
+            const columnInfos = await getColumns(client, rel);
+            const knownColumns = columnInfos.map((c) => c.name);
+            const primaryKey = await getPrimaryKey(client, rel);
+            const pkColumnNames = primaryKey?.columns ?? [];
+            const pkIdents = pkColumnNames.map((name) => resolveColumn(args.schema, args.table, name, knownColumns));
+            return { columnByName: new Map(columnInfos.map((c) => [c.name, c])), knownColumns, pkIdents, pkColumnNames };
+        }, { operation: 'insert_batch' });
+        // Only pin the guard's keyChecksum to the primary key when the caller
+        // supplies every PK column's value explicitly. keyChecksum exists to
+        // detect "the set of rows this statement affects drifted between dry
+        // run and confirm" — meaningful for UPDATE/DELETE, which filter
+        // *pre-existing* rows. INSERT has no pre-existing rows to drift: when
+        // the PK is server-generated (IDENTITY/SERIAL/DEFAULT nextval), the
+        // dry run's own INSERT still consumes real sequence values before its
+        // ROLLBACK (sequences are non-transactional), so the confirm's real
+        // INSERT is guaranteed to receive *different* generated keys than the
+        // dry run previewed — a false-positive GUARD_ROW_DRIFT on every single
+        // confirm, not a rare race. sqlHash (which hashes the input params,
+        // including any explicit PK values) already fully covers "did the
+        // input change between dry run and confirm" for INSERT, since its
+        // outcome depends only on its input, not on concurrent DB state the
+        // way a WHERE-matched row set does. So: explicit PK in the batch →
+        // keep the checksum (it's meaningful and stable across both calls);
+        // server-generated PK → skip it and rely on rowCount instead.
+        const keyColumns = pkColumnNames.length > 0 && pkColumnNames.every((name) => args.columns.includes(name)) ? pkIdents : [];
+        const columnIdents = args.columns.map((name) => resolveColumn(args.schema, args.table, name, knownColumns));
+        const dataTypeOf = (name) => {
+            const info = columnByName.get(name);
+            if (info === undefined) {
+                // resolveColumn above already validated every name in args.columns
+                // against knownColumns, so this is unreachable — kept as a hard
+                // failure rather than silently casting to a made-up type.
+                throw new Error(`column "${name}" resolved but has no catalog entry`);
+            }
+            return info.dataType;
+        };
+        const threshold = readInt(process.env, 'PG_MCP_INSERT_BULK_THRESHOLD', { default: 1000, min: 1 });
+        const built = buildInsertSql(rel.schema, rel.name, columnIdents, args.columns, args.rows, dataTypeOf, threshold);
+        const sql = built.sql + buildOnConflictSql(args.onConflict, args.schema, args.table, knownColumns);
+        const params = built.params;
+        const outcome = await runGuardedMutation({
+            profile,
+            capability: 'write',
+            operation: 'insert_batch',
+            sql,
+            params,
+            keyColumns,
+            // The other half of the paragraph above, and the reason a production
+            // profile can use this tool at all: with a server-generated PK,
+            // `keyColumns` is empty by design, and production would otherwise refuse
+            // the call up front for "no primary key" — a diagnosis that is false
+            // (the table has one) and a remedy that is impossible (GENERATED ALWAYS
+            // rejects an explicit value without OVERRIDING SYSTEM VALUE, which this
+            // tool never emits). See `core/guards.ts#noPreexistingRows` for why
+            // rowCount is a complete receipt for an INSERT specifically.
+            noPreexistingRows: true,
+            confirm: args.confirm,
+            expect: toExpectToken(args.expect),
+            allowRowDrift: args.allowRowDrift,
+        });
+        return formatOutcome(outcome);
+    }
+    catch (err) {
+        return toToolResult(err);
+    }
+});
+//# sourceMappingURL=insert_batch.js.map

package/dist/tools/insert_batch.js.map

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

package/dist/tools/list_objects.js

@@ -0,0 +1,160 @@
+import { z } from 'zod';
+import { loadProfiles } from '../config/profiles.js';
+import { PgMcpError, toToolResult } from '../core/errors.js';
+import { formatOutcome } from '../core/format.js';
+import { resolveSchemaScope } from '../core/identifiers.js';
+import { resolveLimits } from '../core/limits.js';
+import { computeShapeHash, decodeCursor, encodeCursor } from '../core/paginate.js';
+import { withSession } from '../db/session.js';
+import { defineTool, profileParam } from './_shared.js';
+import { gatherObjects, OBJECT_KINDS } from './_object_kinds.js';
+/**
+ * `postgres_list_objects` — the discovery entry point: schemas, tables,
+ * views, materialized views, sequences, functions, enum types, and
+ * extensions, in one paginated listing.
+ *
+ * Pagination is a plain in-memory keyset over `(schema, kind, name)`: every
+ * `db/catalog.ts` listing here is a `pg_catalog` metadata query (never large
+ * in absolute row-byte terms, even across a 5000-table database — the actual
+ * risk is response *token* budget, not query cost), so the whole matching set
+ * is gathered once, sorted deterministically, and sliced — cursor and shape
+ * hash come from `core/paginate.ts`'s low-level primitives directly
+ * (`encodeCursor`/`decodeCursor`/`computeShapeHash`) rather than its
+ * SQL-building helpers (`SortColumn`/`buildKeysetWhere`), which require a
+ * `SafeIdent` this cross-kind, in-memory merge has no use for.
+ */
+const DEFAULT_PAGE_SIZE = 200;
+const MAX_PAGE_SIZE = 2000;
+const CURSOR_COLUMNS = ['schema', 'kind', 'name'];
+const inputSchema = z.object({
+    ...profileParam,
+    schemas: z
+        .array(z.string().min(1))
+        .optional()
+        .describe('Restrict to these schemas. Omit for every schema in scope (Profile.schemas, or every non-system schema).'),
+    kinds: z
+        .array(z.enum(OBJECT_KINDS))
+        .optional()
+        .describe(`Restrict to these object kinds (${OBJECT_KINDS.join(', ')}). Omit for every kind.`),
+    namePattern: z
+        .string()
+        .max(200)
+        .optional()
+        .describe('SQL LIKE pattern (% and _ wildcards, \\ escapes a literal % or _), matched case-insensitively against the object name via ILIKE.'),
+    pageSize: z
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_PAGE_SIZE)
+        .optional()
+        .describe(`Objects per page (max ${MAX_PAGE_SIZE}). Defaults to ${DEFAULT_PAGE_SIZE}, further capped by the profile row limit.`),
+    cursor: z.string().optional().describe('Opaque pagination cursor — pass back the previous call\'s nextCursor verbatim to fetch the next page.'),
+});
+function keyOf(o) {
+    return CURSOR_COLUMNS.map((c) => o[c]);
+}
+function compareKeys(a, b) {
+    for (let i = 0; i < a.length; i++) {
+        const cmp = (a[i] ?? '').localeCompare(b[i] ?? '');
+        if (cmp !== 0)
+            return cmp;
+    }
+    return 0;
+}
+/**
+ * Extracts the `(schema, kind, name)` key from a decoded cursor's sort
+ * values, in `CURSOR_COLUMNS` order. Requires an exact column-name match
+ * against `CURSOR_COLUMNS` — a cursor whose shape hash happens to match (same
+ * profile/schemas/kinds/namePattern) but whose `v` entries name different or
+ * missing columns is rejected outright rather than silently defaulting the
+ * absent ones to `''`, which previously restarted pagination from page 1
+ * (every key comparing `<= ['', '', '']`) instead of surfacing an error.
+ */
+export function cursorKeyFromValues(values) {
+    const byColumn = new Map(values.map((v) => [v.column, v.value]));
+    const gotColumns = new Set(byColumn.keys());
+    const wantColumns = new Set(CURSOR_COLUMNS);
+    const matches = gotColumns.size === wantColumns.size && CURSOR_COLUMNS.every((c) => gotColumns.has(c));
+    if (!matches) {
+        throw new PgMcpError({
+            code: 'CURSOR_INVALID',
+            message: `pagination cursor is invalid: expected columns [${CURSOR_COLUMNS.join(', ')}], got [${[...gotColumns].join(', ')}]`,
+            hint: 'omit the cursor to start from the first page, or pass back the exact nextCursor value from the previous call',
+        });
+    }
+    return CURSOR_COLUMNS.map((c) => String(byColumn.get(c) ?? ''));
+}
+export const listObjectsTool = defineTool('postgres_list_objects', {
+    title: 'List PostgreSQL objects',
+    description: 'Paginated listing of schemas, tables, views, materialized views, sequences, functions, enum types, and ' +
+        'extensions in scope for a profile — the entry point for discovering what exists before describing or ' +
+        'querying it. Filter by schema(s), kind(s), and a name pattern. Always returns a nextCursor when more ' +
+        'objects remain; pass it back verbatim as cursor to continue. ' +
+        'The "enum" kind lists enum types only — domain and composite types are not covered by any kind here.',
+    inputSchema,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+}, async (args) => {
+    try {
+        const registry = loadProfiles();
+        const profile = registry.get(args.profile);
+        const filtered = await withSession(profile, async (client) => {
+            const schemaNames = await resolveSchemaScope(client, profile, args.schemas);
+            return gatherObjects(client, schemaNames, args.kinds, args.namePattern);
+        }, { operation: 'list_objects' });
+        const shapeHash = computeShapeHash({
+            profile: profile.alias,
+            schemas: args.schemas ?? null,
+            kinds: args.kinds ?? null,
+            namePattern: args.namePattern ?? null,
+        });
+        let startIndex = 0;
+        if (args.cursor !== undefined) {
+            const afterKey = cursorKeyFromValues(decodeCursor(args.cursor, shapeHash));
+            const idx = filtered.findIndex((o) => compareKeys(keyOf(o), afterKey) > 0);
+            startIndex = idx === -1 ? filtered.length : idx;
+        }
+        const limits = resolveLimits(profile.maxRows, {}, process.env);
+        const pageSize = Math.min(args.pageSize ?? DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE, limits.maxRows);
+        const page = filtered.slice(startIndex, startIndex + pageSize);
+        const hasMore = startIndex + page.length < filtered.length;
+        const last = page[page.length - 1];
+        const nextCursor = hasMore && last !== undefined ? encodeCursor(CURSOR_COLUMNS.map((c) => ({ column: c, value: last[c] })), shapeHash) : undefined;
+        const rows = page.map((o) => ({
+            kind: o.kind,
+            schema: o.schema,
+            name: o.name,
+            oid: o.oid,
+            owner: o.owner,
+            comment: o.comment,
+            details: o.details,
+        }));
+        return formatOutcome({
+            kind: 'rows',
+            columns: [
+                { name: 'kind', dataTypeId: 25 },
+                { name: 'schema', dataTypeId: 25 },
+                { name: 'name', dataTypeId: 25 },
+                { name: 'oid', dataTypeId: 23 },
+                { name: 'owner', dataTypeId: 25 },
+                { name: 'comment', dataTypeId: 25 },
+                { name: 'details', dataTypeId: 114 },
+            ],
+            rows,
+            rowCount: filtered.length,
+            truncated: hasMore,
+            truncationNoun: 'object',
+            // The cap that actually cut this page is `pageSize`, never the
+            // profile's row cap — `gatherObjects` already returned the whole
+            // matching set in memory before this slice, so the row cap in
+            // `limits` never applies here at all (see Q5: the review measured
+            // the text marker misreporting "row cap 500" when pageSize:2 was
+            // what actually truncated the page).
+            ...(hasMore ? { rowCapLabel: `pageSize ${pageSize}` } : {}),
+            ...(nextCursor === undefined ? {} : { nextCursor }),
+        }, { limits });
+    }
+    catch (err) {
+        return toToolResult(err);
+    }
+});
+//# sourceMappingURL=list_objects.js.map

package/dist/tools/list_objects.js.map

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

package/dist/tools/prepare_migration.js

@@ -0,0 +1,112 @@
+import { z } from 'zod';
+import { loadProfiles } from '../config/profiles.js';
+import { toToolResult } from '../core/errors.js';
+import { formatOutcome } from '../core/format.js';
+import { resolveLimits, truncateRows } from '../core/limits.js';
+import { diffSnapshots } from '../snapshot/diff.js';
+import { planMigration } from '../snapshot/migrate.js';
+import { defineTool, profileParam } from './_shared.js';
+import { resolveSnapshotSource, snapshotSourceSchema } from './_snapshot_io.js';
+/**
+ * `postgres_prepare_migration` — diffs two schema snapshots (same `before`/
+ * `after` sources as `postgres_schema_diff`) and turns the result into an
+ * ordered, risk-annotated SQL plan via `snapshot/migrate.ts#planMigration`.
+ *
+ * **This tool only emits SQL text. It never executes any of it, in any way,
+ * on any database.** `migrate.ts` itself never imports `db/session.ts` or
+ * touches a `Client`/`Pool` — see that module's header — so there is no code
+ * path here that could run a statement even by accident. Review the plan,
+ * then apply it yourself statement by statement with whatever tool you trust
+ * for that (`postgres_execute_sql`, `psql`, a real migration runner).
+ *
+ * Each statement in the response carries: the SQL itself, a specific risk
+ * level and note (what could actually go wrong, not a bare label), an
+ * optional precondition query to run first, and either a `down` statement
+ * that genuinely restores the prior state or a `downNote` explaining why one
+ * cannot be produced honestly (a `DROP COLUMN`'s data is gone; there is no
+ * lying `down` for that). `migrate.ts`'s module doc lists, once, every change
+ * kind this generator cannot build SQL for — those surface in `unsupported`
+ * instead of being silently skipped.
+ */
+const inputSchema = z.object({
+    ...profileParam,
+    before: snapshotSourceSchema.describe('The baseline side of the comparison.'),
+    after: snapshotSourceSchema.describe('The target side of the comparison — the plan migrates before -> after.'),
+    concurrentIndexes: z
+        .boolean()
+        .optional()
+        .describe('Use CREATE/DROP INDEX CONCURRENTLY where safe (default true). CONCURRENTLY cannot run in the same transaction ' +
+        'block as any other statement in this plan — pass false if you intend to apply the plan as one transaction.'),
+    maxStatements: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Caps the number of statements included before truncation. Defaults to the profile row limit.'),
+});
+/**
+ * `unsupported` gets the same treatment as truncation — a count and a prose
+ * message beside the array — deliberately. `statementCount`, `totalStatements`
+ * and `truncated: false` all read as "this plan is complete"; an array the
+ * reader has to think to inspect is not a counterweight to three of those.
+ */
+function unsupportedHint(unsupported) {
+    const named = unsupported
+        .slice(0, 3)
+        .map((u) => `${u.path} (${u.objectType})`)
+        .join(', ');
+    const rest = unsupported.length > 3 ? `, and ${unsupported.length - 3} more` : '';
+    return (`${unsupported.length} change(s) in this diff could not be turned into SQL and are NOT in the statements below: ` +
+        `${named}${rest}. Applying this plan does not fully migrate before -> after — see the unsupported array for the ` +
+        'reason for each, and handle those manually.');
+}
+/** An explicit, actionable truncation message: what was kept, what was cut, how to narrow. */
+function truncationHint(kept, total, cutAt) {
+    const at = cutAt === undefined ? 'the cap' : `${cutAt.path} (${cutAt.objectType} ${cutAt.changeKind})`;
+    return `showing ${kept} of ${total} statements; truncated at ${at} — narrow before/after with a schemas scope, or raise maxStatements. Applying a truncated plan is unsafe: later statements this plan depends on may be missing.`;
+}
+export const prepareMigrationTool = defineTool('postgres_prepare_migration', {
+    title: 'Prepare an ordered SQL migration plan (SQL only — never executed)',
+    description: 'Diffs two schema snapshots (same before/after sources as postgres_schema_diff: live database or a file from ' +
+        'postgres_schema_snapshot) and returns an ordered, dependency-safe, risk-annotated SQL plan. This tool ONLY ' +
+        'emits SQL text — it never runs any of it against any database, under any circumstance. Each statement carries ' +
+        'a risk level with a specific reason, an optional precondition query, and either a genuine down statement or an ' +
+        'explanation of why one cannot restore the prior state. Change kinds this generator cannot build SQL for are ' +
+        'listed in the response\'s unsupported array, never silently skipped. Review and apply the plan yourself, ' +
+        'statement by statement, with postgres_execute_sql or another tool you trust.',
+    inputSchema,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+}, async (args) => {
+    try {
+        const registry = loadProfiles();
+        const profile = registry.get(args.profile);
+        const [before, after] = await Promise.all([
+            resolveSnapshotSource(args.before, args.profile),
+            resolveSnapshotSource(args.after, args.profile),
+        ]);
+        const changes = diffSnapshots(before, after);
+        const concurrentIndexes = args.concurrentIndexes ?? true;
+        const plan = planMigration(changes, { concurrentIndexes });
+        const limits = resolveLimits(profile.maxRows, args.maxStatements === undefined ? {} : { maxRows: args.maxStatements }, process.env);
+        const { rows: kept, truncation } = truncateRows(plan.statements, limits, (s) => JSON.stringify(s));
+        const truncated = truncation.reason !== null;
+        const data = {
+            before: { database: before.database },
+            after: { database: after.database },
+            concurrentIndexes,
+            statementCount: kept.length,
+            totalStatements: plan.statements.length,
+            statements: kept,
+            truncated,
+            ...(truncated ? { truncationMessage: truncationHint(kept.length, plan.statements.length, plan.statements[kept.length]) } : {}),
+            unsupportedCount: plan.unsupported.length,
+            ...(plan.unsupported.length > 0 ? { unsupportedMessage: unsupportedHint(plan.unsupported) } : {}),
+            unsupported: plan.unsupported,
+        };
+        return formatOutcome({ kind: 'report', data });
+    }
+    catch (err) {
+        return toToolResult(err);
+    }
+});
+//# sourceMappingURL=prepare_migration.js.map

package/dist/tools/prepare_migration.js.map

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