@ecubelabs/mysql-mcp 0.0.0-stage → 0.0.1

package/dist/src/catalog/usage.js

@@ -0,0 +1,164 @@
+import SqlParser from 'node-sql-parser';
+const { Parser } = SqlParser;
+const parser = new Parser();
+function cteNames(ast) {
+    const names = new Set();
+    const visit = (node) => {
+        if (node == null || typeof node !== 'object' || node instanceof Date) {
+            return;
+        }
+        const obj = node;
+        if (Array.isArray(obj.with)) {
+            for (const entry of obj.with) {
+                if (!entry || typeof entry !== 'object') {
+                    continue;
+                }
+                const name = entry.name;
+                if (name && typeof name === 'object') {
+                    const value = name.value;
+                    if (typeof value === 'string') {
+                        names.add(value.toLowerCase());
+                    }
+                }
+            }
+        }
+        for (const value of Object.values(obj)) {
+            if (Array.isArray(value)) {
+                for (const item of value) {
+                    visit(item);
+                }
+            }
+            else {
+                visit(value);
+            }
+        }
+    };
+    visit(ast);
+    return names;
+}
+function referencesFromTableList(sql, commonTableExpressions) {
+    const seen = new Set();
+    const references = [];
+    for (const encoded of parser.tableList(sql, { database: 'mysql' })) {
+        const parts = encoded.split('::');
+        const schema = parts[1] && parts[1] !== 'null' ? parts[1] : null;
+        const table = parts.slice(2).join('::');
+        if (!table) {
+            continue;
+        }
+        if (!schema && commonTableExpressions.has(table.toLowerCase())) {
+            continue;
+        }
+        const key = `${schema ?? ''}.${table}`.toLowerCase();
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        references.push({ schema, table });
+    }
+    return references;
+}
+function collectAliases(node, aliases) {
+    if (node == null || typeof node !== 'object' || node instanceof Date) {
+        return;
+    }
+    const obj = node;
+    if (obj.type !== 'column_ref' && typeof obj.table === 'string' && (typeof obj.db === 'string' || obj.db === null)) {
+        const reference = {
+            schema: typeof obj.db === 'string' ? obj.db : null,
+            table: obj.table,
+        };
+        aliases.set(obj.table.toLowerCase(), reference);
+        if (typeof obj.as === 'string') {
+            aliases.set(obj.as.toLowerCase(), reference);
+        }
+    }
+    for (const value of Object.values(obj)) {
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                collectAliases(item, aliases);
+            }
+        }
+        else {
+            collectAliases(value, aliases);
+        }
+    }
+}
+function columnEndpoint(node, aliases, references) {
+    if (!node || typeof node !== 'object') {
+        return null;
+    }
+    const obj = node;
+    if (obj.type !== 'column_ref' || typeof obj.column !== 'string') {
+        return null;
+    }
+    if (typeof obj.table === 'string') {
+        const table = aliases.get(obj.table.toLowerCase());
+        return table ? { ...table, column: obj.column } : null;
+    }
+    return references.length === 1 ? { ...references[0], column: obj.column } : null;
+}
+function collectJoins(node, aliases, references, seen, joins) {
+    if (node == null || typeof node !== 'object' || node instanceof Date) {
+        return;
+    }
+    const obj = node;
+    if (obj.type === 'binary_expr' && obj.operator === '=') {
+        const left = columnEndpoint(obj.left, aliases, references);
+        const right = columnEndpoint(obj.right, aliases, references);
+        if (left && right) {
+            const a = `${left.schema ?? ''}.${left.table}.${left.column}`;
+            const b = `${right.schema ?? ''}.${right.table}.${right.column}`;
+            const key = [a, b].sort().join('\u0000').toLowerCase();
+            if (!seen.has(key)) {
+                seen.add(key);
+                joins.push({ a: left, b: right });
+            }
+        }
+    }
+    for (const value of Object.values(obj)) {
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                collectJoins(item, aliases, references, seen, joins);
+            }
+        }
+        else {
+            collectJoins(value, aliases, references, seen, joins);
+        }
+    }
+}
+export function prepareCatalogQuery(sql) {
+    try {
+        const ast = parser.astify(sql, { database: 'mysql' });
+        const references = referencesFromTableList(sql, cteNames(ast));
+        const aliases = new Map();
+        collectAliases(ast, aliases);
+        const joins = [];
+        collectJoins(ast, aliases, references, new Set(), joins);
+        return { references, joins };
+    }
+    catch {
+        return { references: [], joins: [] };
+    }
+}
+export function resultColumnNames(payload) {
+    try {
+        const parsed = JSON.parse(payload);
+        if (!Array.isArray(parsed)) {
+            return [];
+        }
+        const names = new Set();
+        for (const row of parsed) {
+            if (!row || typeof row !== 'object' || Array.isArray(row)) {
+                continue;
+            }
+            for (const name of Object.keys(row)) {
+                names.add(name);
+            }
+        }
+        return [...names];
+    }
+    catch {
+        return [];
+    }
+}

package/dist/src/config/index.js

@@ -0,0 +1,244 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+function parseSchemaPermissions(permissionsString) {
+    const permissions = {};
+    if (!permissionsString) {
+        return permissions;
+    }
+    for (const pair of permissionsString.split(',')) {
+        const [schema, value] = pair.split(':');
+        if (schema && value) {
+            permissions[schema.trim()] = value.trim() === 'true';
+        }
+    }
+    return permissions;
+}
+function readSSLFile(filePath, label) {
+    try {
+        if (!fs.existsSync(filePath)) {
+            throw new Error(`SSL ${label} file not found: ${filePath}`);
+        }
+        const data = fs.readFileSync(filePath);
+        if (data.length === 0) {
+            throw new Error(`SSL ${label} file is empty: ${filePath}`);
+        }
+        return data;
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            if (error.message.startsWith('SSL ')) {
+                throw error;
+            }
+            throw new Error(`Failed to read SSL ${label}: ${error.message}`);
+        }
+        throw error;
+    }
+}
+function readCACertificate(filePath) {
+    return readSSLFile(filePath, 'CA certificate');
+}
+const PACKAGE_NAME = '@ecubelabs/mysql-mcp';
+export function readPackageVersion(startDir) {
+    let dir = startDir;
+    for (;;) {
+        try {
+            const manifest = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+            if (manifest.name === PACKAGE_NAME && typeof manifest.version === 'string') {
+                return manifest.version;
+            }
+        }
+        catch {
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            return undefined;
+        }
+        dir = parent;
+    }
+}
+export const MYSQL_PROFILE = (process.env.MYSQL_PROFILE ?? '').trim().toLowerCase();
+const WRITE_FORBIDDEN_PROFILES = new Set(['prod', 'production']);
+export const IS_WRITE_FORBIDDEN_PROFILE = WRITE_FORBIDDEN_PROFILES.has(MYSQL_PROFILE);
+export const PROFILE_LABEL = MYSQL_PROFILE ? MYSQL_PROFILE.toUpperCase() : 'UNSPECIFIED';
+const DEFAULT_CODE_BRANCH = {
+    stage: 'develop',
+    staging: 'develop',
+    dev: 'develop',
+    develop: 'develop',
+    prod: 'main',
+    production: 'main',
+};
+export const CODE_BRANCH = process.env.MYSQL_CODE_BRANCH?.trim() || DEFAULT_CODE_BRANCH[MYSQL_PROFILE] || '';
+function parseAppSchemas(raw) {
+    if (!raw) {
+        return [];
+    }
+    const entries = [];
+    const seen = new Set();
+    for (const entry of raw.split(/[;\n]/)) {
+        const trimmed = entry.trim();
+        if (!trimmed || trimmed.startsWith('#')) {
+            continue;
+        }
+        const firstColon = trimmed.indexOf(':');
+        if (firstColon === -1) {
+            console.error(`[config] ignoring MYSQL_APP_SCHEMAS entry "${trimmed}": expected "app:schema" or "app:schema:description".`);
+            continue;
+        }
+        const app = trimmed.slice(0, firstColon).trim();
+        const rest = trimmed.slice(firstColon + 1);
+        const secondColon = rest.indexOf(':');
+        const schema = (secondColon === -1 ? rest : rest.slice(0, secondColon)).trim();
+        const description = secondColon === -1 ? undefined : rest.slice(secondColon + 1).trim() || undefined;
+        if (!app || !schema) {
+            console.error(`[config] ignoring MYSQL_APP_SCHEMAS entry "${trimmed}": app and schema must both be non-empty.`);
+            continue;
+        }
+        const pair = `${app.toLowerCase()}\u0000${schema.toLowerCase()}`;
+        if (seen.has(pair)) {
+            console.error(`[config] MYSQL_APP_SCHEMAS repeats "${app}:${schema}"; keeping the first.`);
+            continue;
+        }
+        seen.add(pair);
+        entries.push({ app, schema, description });
+    }
+    return entries;
+}
+export const APP_SCHEMAS = parseAppSchemas(process.env.MYSQL_APP_SCHEMAS);
+export const MYSQL_CATALOG_ENABLED = process.env.MYSQL_CATALOG_ENABLED !== 'false';
+export const MYSQL_CATALOG_PATH = process.env.MYSQL_CATALOG_PATH?.trim() || undefined;
+function parseCatalogTtl(raw) {
+    if (!raw) {
+        return 24;
+    }
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value <= 0) {
+        console.error(`[config] ignoring MYSQL_CATALOG_TTL_HOURS="${raw}": expected a positive number; using 24.`);
+        return 24;
+    }
+    return value;
+}
+export const MYSQL_CATALOG_TTL_HOURS = parseCatalogTtl(process.env.MYSQL_CATALOG_TTL_HOURS);
+export const MYSQL_DOCS_REPO = process.env.MYSQL_DOCS_REPO?.trim() || undefined;
+export const ENABLE_LOGGING = process.env.ENABLE_LOGGING === 'true' || process.env.ENABLE_LOGGING === '1';
+export const PACKAGE_VERSION = readPackageVersion(path.dirname(fileURLToPath(import.meta.url))) ?? 'unknown';
+export const MYSQL_DB = process.env.MYSQL_DB?.trim() || undefined;
+const envFlag = (name) => process.env[name] === 'true';
+const writeFlag = (name) => (IS_WRITE_FORBIDDEN_PROFILE ? false : envFlag(name));
+if (IS_WRITE_FORBIDDEN_PROFILE) {
+    const requested = [
+        ...['ALLOW_INSERT_OPERATION', 'ALLOW_UPDATE_OPERATION', 'ALLOW_DELETE_OPERATION', 'ALLOW_DDL_OPERATION'].filter(envFlag),
+        ...[
+            'SCHEMA_INSERT_PERMISSIONS',
+            'SCHEMA_UPDATE_PERMISSIONS',
+            'SCHEMA_DELETE_PERMISSIONS',
+            'SCHEMA_DDL_PERMISSIONS',
+        ].filter((name) => Boolean(process.env[name]?.trim())),
+    ];
+    if (requested.length > 0) {
+        console.error(`[config] profile "${MYSQL_PROFILE}" is read-only by policy; ignoring ${requested.join(', ')}.`);
+    }
+}
+export const ALLOW_INSERT_OPERATION = writeFlag('ALLOW_INSERT_OPERATION');
+export const ALLOW_UPDATE_OPERATION = writeFlag('ALLOW_UPDATE_OPERATION');
+export const ALLOW_DELETE_OPERATION = writeFlag('ALLOW_DELETE_OPERATION');
+export const ALLOW_DDL_OPERATION = writeFlag('ALLOW_DDL_OPERATION');
+export const MYSQL_DISABLE_READ_ONLY_TRANSACTIONS = process.env.MYSQL_DISABLE_READ_ONLY_TRANSACTIONS === 'true';
+function parsePositiveInt(name, raw, fallback) {
+    if (!raw) {
+        return fallback;
+    }
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value < 1) {
+        console.error(`[config] ignoring ${name}="${raw}": expected a positive integer; using ${fallback}.`);
+        return fallback;
+    }
+    return Math.floor(value);
+}
+function parsePortEnv(name, raw) {
+    const trimmed = raw?.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    const port = Number(trimmed);
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        console.error(`[config] ignoring ${name}="${raw}": expected an integer between 0 and 65535.`);
+        return undefined;
+    }
+    return port;
+}
+export const MYSQL_MAX_TIMEOUT_SECONDS = parsePositiveInt('MYSQL_MAX_TIMEOUT_SECONDS', process.env.MYSQL_MAX_TIMEOUT_SECONDS, 30);
+export const MYSQL_DEFAULT_TIMEOUT_SECONDS = Math.min(10, MYSQL_MAX_TIMEOUT_SECONDS);
+export const MYSQL_CATALOG_TIMEOUT_SECONDS = parsePositiveInt('MYSQL_CATALOG_TIMEOUT_SECONDS', process.env.MYSQL_CATALOG_TIMEOUT_SECONDS, 60);
+export const MAX_RESPONSE_ROWS = parsePositiveInt('MYSQL_MAX_RESPONSE_ROWS', process.env.MYSQL_MAX_RESPONSE_ROWS, 5000);
+export const MYSQL_POOL_SIZE = parsePositiveInt('MYSQL_POOL_SIZE', process.env.MYSQL_POOL_SIZE, 10);
+export const MYSQL_QUEUE_LIMIT = parsePositiveInt('MYSQL_QUEUE_LIMIT', process.env.MYSQL_QUEUE_LIMIT, 100);
+export const MYSQL_CONNECT_TIMEOUT = parsePositiveInt('MYSQL_CONNECT_TIMEOUT', process.env.MYSQL_CONNECT_TIMEOUT, 10000);
+export const MYSQL_SOCKET_PATH = process.env.MYSQL_SOCKET_PATH?.trim() || undefined;
+export const MYSQL_HOST = process.env.MYSQL_HOST?.trim() || undefined;
+export const MYSQL_PORT = parsePortEnv('MYSQL_PORT', process.env.MYSQL_PORT) ?? 3306;
+export const DEFAULT_MYSQL_HOST = '127.0.0.1';
+export const MYSQL_SSL_ENABLED = process.env.MYSQL_SSL === 'true';
+export const MYSQL_SSL_REJECT_UNAUTHORIZED = process.env.MYSQL_SSL_REJECT_UNAUTHORIZED === 'true';
+export const MYSQL_SSL_CA_PATH = process.env.MYSQL_SSL_CA?.trim() || undefined;
+export const MYSQL_SSL_CERT_PATH = process.env.MYSQL_SSL_CERT?.trim() || undefined;
+export const MYSQL_SSL_KEY_PATH = process.env.MYSQL_SSL_KEY?.trim() || undefined;
+export const MYSQL_TIMEZONE = process.env.MYSQL_TIMEZONE?.trim() || undefined;
+export const MYSQL_DATE_STRINGS = process.env.MYSQL_DATE_STRINGS === 'true';
+export const MYSQL_BIG_NUMBER_STRINGS = process.env.MYSQL_BIG_NUMBER_STRINGS === 'true';
+export const SSH_REUSE_EXISTING = process.env.MYSQL_SSH_REUSE_EXISTING === 'true';
+export const SSH_CONFIG_HOST = process.env.MYSQL_SSH_CONFIG_HOST?.trim() || undefined;
+export const SSH_HOST = process.env.MYSQL_SSH_HOST?.trim() || undefined;
+export const SSH_USER = process.env.MYSQL_SSH_USER?.trim() || undefined;
+export const SSH_PORT = parsePortEnv('MYSQL_SSH_PORT', process.env.MYSQL_SSH_PORT);
+export const SSH_PRIVATE_KEY_PATH = process.env.MYSQL_SSH_PRIVATE_KEY_PATH?.trim() || undefined;
+export const SSH_PASSPHRASE = process.env.MYSQL_SSH_PASSPHRASE?.trim() || undefined;
+export const SSH_LOCAL_PORT = parsePortEnv('MYSQL_SSH_LOCAL_PORT', process.env.MYSQL_SSH_LOCAL_PORT);
+export const SSH_ENABLED = Boolean(SSH_CONFIG_HOST || SSH_HOST);
+const schemaPermissions = (name) => IS_WRITE_FORBIDDEN_PROFILE ? {} : parseSchemaPermissions(process.env[name]);
+export const SCHEMA_INSERT_PERMISSIONS = schemaPermissions('SCHEMA_INSERT_PERMISSIONS');
+export const SCHEMA_UPDATE_PERMISSIONS = schemaPermissions('SCHEMA_UPDATE_PERMISSIONS');
+export const SCHEMA_DELETE_PERMISSIONS = schemaPermissions('SCHEMA_DELETE_PERMISSIONS');
+export const SCHEMA_DDL_PERMISSIONS = schemaPermissions('SCHEMA_DDL_PERMISSIONS');
+export const isMultiDbMode = !MYSQL_DB;
+const MYSQL_PASS = process.env.MYSQL_PASS ?? '';
+export const mcpConfig = {
+    mysql: {
+        ...(MYSQL_SOCKET_PATH
+            ? { socketPath: MYSQL_SOCKET_PATH }
+            : {
+                host: MYSQL_HOST || DEFAULT_MYSQL_HOST,
+                port: MYSQL_PORT,
+            }),
+        user: process.env.MYSQL_USER?.trim() || 'root',
+        password: MYSQL_PASS,
+        database: MYSQL_DB,
+        connectionLimit: MYSQL_POOL_SIZE,
+        waitForConnections: true,
+        queueLimit: MYSQL_QUEUE_LIMIT,
+        enableKeepAlive: true,
+        keepAliveInitialDelay: 0,
+        connectTimeout: MYSQL_CONNECT_TIMEOUT,
+        authPlugins: {
+            mysql_clear_password: () => () => Buffer.from(MYSQL_PASS),
+        },
+        ...(MYSQL_SSL_ENABLED
+            ? {
+                ssl: {
+                    rejectUnauthorized: MYSQL_SSL_REJECT_UNAUTHORIZED,
+                    ...(MYSQL_SSL_CA_PATH ? { ca: readCACertificate(MYSQL_SSL_CA_PATH) } : {}),
+                    ...(MYSQL_SSL_CERT_PATH ? { cert: readSSLFile(MYSQL_SSL_CERT_PATH, 'client certificate') } : {}),
+                    ...(MYSQL_SSL_KEY_PATH ? { key: readSSLFile(MYSQL_SSL_KEY_PATH, 'client private key') } : {}),
+                },
+            }
+            : {}),
+        ...(MYSQL_TIMEZONE ? { timezone: MYSQL_TIMEZONE } : {}),
+        ...(MYSQL_DATE_STRINGS ? { dateStrings: true } : {}),
+        ...(MYSQL_BIG_NUMBER_STRINGS ? { supportBigNumbers: true, bigNumberStrings: true } : {}),
+    },
+};
+export function describeConfiguredTarget() {
+    return MYSQL_SOCKET_PATH ? `socket: ${MYSQL_SOCKET_PATH}` : `${MYSQL_HOST || DEFAULT_MYSQL_HOST}:${MYSQL_PORT}`;
+}
+export { readCACertificate, readSSLFile };

package/dist/src/db/diagnose.js

@@ -0,0 +1,189 @@
+const ER_QUERY_TIMEOUT = 3024;
+export function isQueryTimeoutError(error) {
+    if (error == null || typeof error !== 'object') {
+        return false;
+    }
+    const candidate = error;
+    return candidate.errno === ER_QUERY_TIMEOUT || candidate.code === 'ER_QUERY_TIMEOUT';
+}
+const ROW_FIELDS = [
+    { key: 'rows_examined_per_scan', unit: 'rows/scan' },
+    { key: 'rows', unit: 'rows' },
+    { key: 'rows_produced_per_join', unit: 'rows out' },
+];
+function readRows(node) {
+    for (const { key, unit } of ROW_FIELDS) {
+        const value = node[key];
+        const numeric = typeof value === 'string' ? Number(value) : value;
+        if (typeof numeric === 'number' && Number.isFinite(numeric)) {
+            return { value: numeric, unit };
+        }
+    }
+    return null;
+}
+export function collectPlanTables(node) {
+    const out = [];
+    const visit = (value) => {
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                visit(item);
+            }
+            return;
+        }
+        if (value == null || typeof value !== 'object') {
+            return;
+        }
+        const obj = value;
+        if (typeof obj.access_type === 'string' && typeof obj.table_name === 'string') {
+            out.push({
+                name: obj.table_name,
+                accessType: obj.access_type,
+                rows: readRows(obj),
+                key: typeof obj.key === 'string' ? obj.key : null,
+                condition: typeof obj.attached_condition === 'string' && obj.attached_condition
+                    ? obj.attached_condition
+                    : null,
+                synthetic: obj.table_name.startsWith('<') || 'materialized_from_subquery' in obj,
+            });
+        }
+        for (const child of Object.values(obj)) {
+            visit(child);
+        }
+    };
+    visit(node);
+    return out;
+}
+export function parseExplainPayload(rows) {
+    const first = Array.isArray(rows) ? rows[0] : rows;
+    if (first == null || typeof first !== 'object') {
+        return null;
+    }
+    const value = Object.values(first)[0];
+    if (typeof value === 'object' && value !== null) {
+        return value;
+    }
+    if (typeof value !== 'string') {
+        return null;
+    }
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return null;
+    }
+}
+const MAX_PLAN_JSON_CHARS = 12_000;
+function formatRows(rows) {
+    if (rows == null) {
+        return 'rows: unknown';
+    }
+    return `${rows.unit}: ~${Math.round(rows.value).toLocaleString('en-US')}`;
+}
+function describeIndexes(facts) {
+    if (facts.indexes.length === 0) {
+        return 'none recorded';
+    }
+    return facts.indexes.map((index) => `${index.name}(${index.columns.join(', ')})`).join(', ');
+}
+function labelTables(input, tables) {
+    return tables.map((table) => {
+        if (table.synthetic) {
+            return { table, canonical: table.name, label: table.name };
+        }
+        const facts = input.lookupIndexes(table.name);
+        const resolved = input.qualifiers.get(table.name.toLowerCase());
+        const canonical = facts
+            ? `${facts.schema}.${facts.table}`
+            : resolved
+                ? `${resolved.schema ? `${resolved.schema}.` : ''}${resolved.table}`
+                : table.name;
+        const alias = table.name.toLowerCase();
+        const named = canonical.toLowerCase() === alias || canonical.toLowerCase().endsWith(`.${alias}`);
+        return { table, canonical, label: named ? canonical : `${canonical} (${table.name})` };
+    });
+}
+function renderIndexSection(input, tables) {
+    const seen = new Set();
+    const lines = [];
+    for (const { table, canonical } of tables) {
+        if (table.synthetic) {
+            continue;
+        }
+        if (seen.has(canonical.toLowerCase())) {
+            continue;
+        }
+        seen.add(canonical.toLowerCase());
+        const facts = input.lookupIndexes(table.name);
+        if (!facts) {
+            lines.push(`  ${canonical}: not in the local catalog - its index list is unknown here, so absence of an index cannot be concluded.`);
+            continue;
+        }
+        const staleness = facts.detailStale
+            ? '  (marked stale - may be out of date)'
+            : facts.detailScannedAt === null
+                ? '  (not scanned in detail yet - may be incomplete)'
+                : '';
+        lines.push(`  ${canonical}: ${describeIndexes(facts)}${staleness}`);
+    }
+    return lines;
+}
+export function renderTimeoutDiagnostic(input) {
+    const lines = [
+        `[ABORTED] Query cancelled after exceeding the ${input.timeoutSeconds}s execution limit. No rows were returned.`,
+        '',
+    ];
+    if (!input.plan) {
+        lines.push('[EXPLAIN UNAVAILABLE] The server tried to read the execution plan and could not.', 'Do NOT run EXPLAIN yourself, and do NOT re-run this statement unchanged - it would be cancelled again.', '', ...renderNextSection(input, false));
+        return lines.join('\n');
+    }
+    const tables = labelTables(input, collectPlanTables(input.plan));
+    lines.push('[EXPLAIN ALREADY RUN] The server ran EXPLAIN FORMAT=JSON on this statement and attached the', 'result below. Do NOT run EXPLAIN yourself, and do NOT re-run this statement unchanged.', '');
+    if (tables.length > 0) {
+        lines.push('[PLAN BY TABLE] in join order.');
+        tables.forEach(({ table, label }, i) => {
+            lines.push(`  ${i + 1}. ${label} - access: ${table.accessType}, ${formatRows(table.rows)}, key: ${table.key ?? 'none'}`);
+            if (table.condition) {
+                lines.push(`     condition: ${table.condition}`);
+            }
+        });
+        lines.push('  Reading access: ALL is a full table scan and `index` is a full index scan - both', '  read every row. A non-empty key does NOT mean the filter was narrowed; a full index', '  scan reports one too. const, eq_ref, ref and range did narrow the table.', '  rows/scan is per scan of that table, so an inner table of a join is read once for', '  every row the step above it produced - multiply before calling it cheap.', '');
+    }
+    else {
+        lines.push('[PLAN BY TABLE] no table nodes were recognised in this plan - read the raw plan below.', '');
+    }
+    const indexLines = renderIndexSection(input, tables);
+    if (indexLines.length > 0) {
+        lines.push('[INDEXES] from the local schema catalog, for the tables above:', ...indexLines, '');
+    }
+    const planJson = JSON.stringify(input.plan, null, 2);
+    if (planJson.length <= MAX_PLAN_JSON_CHARS) {
+        lines.push('[FULL PLAN]:', planJson, '');
+    }
+    else {
+        lines.push(`[FULL PLAN] omitted: ${planJson.length.toLocaleString('en-US')} characters, too large to include.`, 'The per-table summary above lists every table the plan touched.', '');
+    }
+    lines.push(...renderNextSection(input, true));
+    return lines.join('\n');
+}
+function renderNextSection(input, hasPlan) {
+    const canExtend = input.timeoutSeconds < input.maxTimeoutSeconds;
+    const lines = [
+        hasPlan
+            ? '[NEXT] Decide from the plan and index lists above, then take exactly one of these:'
+            : '[NEXT] Without a plan, take exactly one of these:',
+        '  1. Rewrite the query so the optimizer can narrow the scan - an indexed filter, a column',
+        '     compared directly instead of wrapped in a function, a tighter range, an aggregate',
+        '     instead of raw rows, or a LIMIT - then retry once. No need to ask the user first,',
+        '     as long as the rewrite still answers what they asked.',
+    ];
+    if (canExtend) {
+        lines.push(`  2. Retry the statement unchanged with timeout_seconds: ${input.maxTimeoutSeconds}. Worth it only if`, hasPlan
+            ? '     the plan looks sound and the query was merely slow. Available once - if it fails'
+            : '     you have reason to think the query was merely slow. Available once - if it fails', '     again, stop and report; do not raise the limit further.');
+    }
+    else {
+        lines.push(`  2. A longer limit is NOT available: this already ran at the ${input.maxTimeoutSeconds}s ceiling, which is the`, '     maximum this server allows. Do not ask for more time.');
+    }
+    lines.push('  3. Stop and ask the user how to proceed. Do this when no rewrite preserves what they', '     asked for - for example when no index covers the column they need to filter on.', '     Give them concrete choices in their own language and in domain terms: a different', '     column to filter on, requesting an index (not possible from this session), or', '     running the query outside this server. Never show them tool argument names.');
+    return lines;
+}