@mokoconsulting/mokomysql-mcp 2.5.4 → 2.6.0

package/source/client.ts

@@ -1,210 +1,210 @@
-/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
- *
- * This file is part of a Moko Consulting project.
- *
- * SPDX-License-Identifier: GPL-3.0-or-later
- *
- * FILE INFORMATION
- * DEFGROUP: mokomysql.Client
- * INGROUP: mokomysql
- * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokomysql-mcp
- * PATH: /src/client.ts
- * VERSION: 01.00.00
- * BRIEF: MySQL client with connection pool management
- */
-
-import mysql from 'mysql2/promise';
-import type { Pool, PoolOptions, FieldPacket, ResultSetHeader } from 'mysql2/promise';
-import { getConnection } from './config.js';
-import { getMarker, markerKey, setMarker } from './state.js';
-import type { MySqlConfig, MySqlConnection } from './types.js';
-
-/** Result of probing a (connection, database) pair for Joomla-ness. */
-export interface JoomlaDetection {
-	/** Whether this target is treated as a Joomla database. */
-	isJoomla: boolean;
-	/** The live table prefix (e.g. "jos_", "vkw4n_"), when known. */
-	prefix: string | null;
-	/** How the verdict was reached — for surfacing in warnings. */
-	source: 'config' | 'marker' | 'auto' | 'none';
-}
-
-export class MysqlClient {
-	private pools: Map<string, Pool> = new Map();
-	private config: MySqlConfig;
-	/** Memoized Joomla verdicts, keyed by `${connectionKey}::${schema}`. */
-	private joomlaCache: Map<string, JoomlaDetection> = new Map();
-
-	constructor(config: MySqlConfig) {
-		this.config = config;
-	}
-
-	/**
-	 * Resolve the canonical identity of a target for binding/keying: the config
-	 * connection key and the effective schema (explicit database or the connection
-	 * default). Keeps callers consistent with how detection and markers are keyed.
-	 */
-	resolveIdentity(connectionName?: string, database?: string): { connKey: string; schema: string } {
-		const { key, conn } = getConnection(this.config, connectionName);
-		return { connKey: key, schema: database ?? conn.database ?? '' };
-	}
-
-	/**
-	 * Determine whether a target is a Joomla database, so writes can be gated.
-	 * Resolution order: in-memory cache → explicit per-connection `joomla` flag
-	 * (authoritative) → persisted sidecar marker (learned on a prior connect) →
-	 * live schema probe for the Joomla signature (`<prefix>extensions` paired with
-	 * `<prefix>assets`). A fresh probe result is persisted as a marker so future
-	 * connects skip the round-trip entirely.
-	 */
-	async detectJoomla(connectionName?: string, database?: string): Promise<JoomlaDetection> {
-		const { key, conn } = getConnection(this.config, connectionName);
-		const schema = database ?? conn.database ?? '';
-		const cacheKey = `${key}::${schema}`;
-		const cached = this.joomlaCache.get(cacheKey);
-		if (cached) return cached;
-
-		// Explicit config flag is authoritative — no probe, and it overrides any marker.
-		if (conn.joomla === true) {
-			return this.cache(cacheKey, { isJoomla: true, prefix: conn.joomlaPrefix ?? null, source: 'config' });
-		}
-		if (conn.joomla === false) {
-			return this.cache(cacheKey, { isJoomla: false, prefix: null, source: 'config' });
-		}
-
-		// Without a resolvable target schema we cannot probe or key a marker.
-		if (!schema) {
-			return this.cache(cacheKey, { isJoomla: false, prefix: null, source: 'none' });
-		}
-
-		// Learned marker from a previous connect — instant, no round-trip.
-		const mKey = markerKey(conn.host, conn.port ?? 3306, schema);
-		const marker = await getMarker(mKey);
-		if (marker) {
-			return this.cache(cacheKey, { isJoomla: marker.joomla, prefix: marker.prefix, source: 'marker' });
-		}
-
-		try {
-			const { rows } = await this.query(
-				"SELECT TABLE_NAME AS name FROM information_schema.TABLES " +
-				"WHERE TABLE_SCHEMA = ? AND TABLE_NAME REGEXP '(extensions|assets)$'",
-				[schema], connectionName,
-			);
-			const names = new Set(rows.map((r) => String((r as Record<string, unknown>).name)));
-			let prefix: string | null = null;
-			for (const name of names) {
-				if (!name.endsWith('extensions')) continue;
-				const candidate = name.slice(0, -'extensions'.length);
-				if (names.has(`${candidate}assets`)) { prefix = candidate; break; }
-			}
-			const verdict: JoomlaDetection = prefix !== null
-				? { isJoomla: true, prefix, source: 'auto' }
-				: { isJoomla: false, prefix: null, source: 'auto' };
-			// Persist what we learned so the next connect just knows.
-			await setMarker(mKey, { joomla: verdict.isJoomla, prefix: verdict.prefix, detectedAt: new Date().toISOString() });
-			return this.cache(cacheKey, verdict);
-		} catch {
-			// Probe failed (permissions, missing schema). Degrade to "none" and do
-			// not cache or persist, so a later successful probe can still classify it.
-			return { isJoomla: false, prefix: null, source: 'none' };
-		}
-	}
-
-	private cache(cacheKey: string, verdict: JoomlaDetection): JoomlaDetection {
-		this.joomlaCache.set(cacheKey, verdict);
-		return verdict;
-	}
-
-	private poolFor(connectionName?: string): Pool {
-		const { key, conn } = getConnection(this.config, connectionName);
-		let pool = this.pools.get(key);
-		if (!pool) {
-			const opts: PoolOptions = {
-				host: conn.host,
-				port: conn.port ?? 3306,
-				user: conn.user,
-				password: conn.password,
-				database: conn.database,
-				connectionLimit: 5,
-				waitForConnections: true,
-				timezone: conn.timezone ?? 'Z',
-				multipleStatements: false,
-			};
-			if (conn.ssl) {
-				// Default to verified TLS. A bare `ssl: true` is never silently
-				// downgraded — callers who must skip verification (trusted internal
-				// hosts with self-signed certs) opt out explicitly via
-				// `ssl: { rejectUnauthorized: false }` in their config.
-				opts.ssl = typeof conn.ssl === 'object'
-					? conn.ssl
-					: { rejectUnauthorized: true };
-			}
-			pool = mysql.createPool(opts);
-			this.pools.set(key, pool);
-			// On first connect, learn (and persist) the Joomla verdict for the
-			// connection's default database so the write-gate knows immediately.
-			// Best-effort and non-blocking — never let it break pool creation.
-			if (conn.database) {
-				void this.detectJoomla(connectionName, conn.database).catch(() => undefined);
-			}
-		}
-		return pool;
-	}
-
-	async query(
-		sql: string,
-		params?: unknown[],
-		connectionName?: string,
-		database?: string,
-	): Promise<{ rows: Record<string, unknown>[]; fields: FieldPacket[] }> {
-		const pool = this.poolFor(connectionName);
-		const p = (params ?? []) as (string | number | null)[];
-		if (database) {
-			const conn = await pool.getConnection();
-			try {
-				await conn.query(`USE \`${database.replace(/`/g, '``')}\``);
-				const [rows, fields] = await conn.query(sql, p);
-				return { rows: rows as Record<string, unknown>[], fields };
-			} finally {
-				conn.release();
-			}
-		}
-		const [rows, fields] = await pool.query(sql, p);
-		return { rows: rows as Record<string, unknown>[], fields };
-	}
-
-	async execute(
-		sql: string,
-		params?: unknown[],
-		connectionName?: string,
-		database?: string,
-	): Promise<{ affectedRows: number; insertId: number; changedRows: number }> {
-		const pool = this.poolFor(connectionName);
-		const p = (params ?? []) as (string | number | null)[];
-		if (database) {
-			const conn = await pool.getConnection();
-			try {
-				await conn.query(`USE \`${database.replace(/`/g, '``')}\``);
-				const [result] = await conn.execute(sql, p);
-				const r = result as ResultSetHeader;
-				return { affectedRows: r.affectedRows ?? 0, insertId: r.insertId ?? 0, changedRows: r.changedRows ?? 0 };
-			} finally {
-				conn.release();
-			}
-		}
-		const [result] = await pool.execute(sql, p);
-		const r = result as ResultSetHeader;
-		return {
-			affectedRows: r.affectedRows ?? 0,
-			insertId: r.insertId ?? 0,
-			changedRows: r.changedRows ?? 0,
-		};
-	}
-
-	async closeAll(): Promise<void> {
-		for (const [, pool] of this.pools) {
-			await pool.end();
-		}
-		this.pools.clear();
-	}
-}
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ *
+ * This file is part of a Moko Consulting project.
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * FILE INFORMATION
+ * DEFGROUP: mokomysql.Client
+ * INGROUP: mokomysql
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokomysql-mcp
+ * PATH: /src/client.ts
+ * VERSION: 01.00.00
+ * BRIEF: MySQL client with connection pool management
+ */
+
+import mysql from 'mysql2/promise';
+import type { Pool, PoolOptions, FieldPacket, ResultSetHeader } from 'mysql2/promise';
+import { getConnection } from './config.js';
+import { getMarker, markerKey, setMarker } from './state.js';
+import type { MySqlConfig, MySqlConnection } from './types.js';
+
+/** Result of probing a (connection, database) pair for Joomla-ness. */
+export interface JoomlaDetection {
+	/** Whether this target is treated as a Joomla database. */
+	isJoomla: boolean;
+	/** The live table prefix (e.g. "jos_", "vkw4n_"), when known. */
+	prefix: string | null;
+	/** How the verdict was reached — for surfacing in warnings. */
+	source: 'config' | 'marker' | 'auto' | 'none';
+}
+
+export class MysqlClient {
+	private pools: Map<string, Pool> = new Map();
+	private config: MySqlConfig;
+	/** Memoized Joomla verdicts, keyed by `${connectionKey}::${schema}`. */
+	private joomlaCache: Map<string, JoomlaDetection> = new Map();
+
+	constructor(config: MySqlConfig) {
+		this.config = config;
+	}
+
+	/**
+	 * Resolve the canonical identity of a target for binding/keying: the config
+	 * connection key and the effective schema (explicit database or the connection
+	 * default). Keeps callers consistent with how detection and markers are keyed.
+	 */
+	resolveIdentity(connectionName?: string, database?: string): { connKey: string; schema: string } {
+		const { key, conn } = getConnection(this.config, connectionName);
+		return { connKey: key, schema: database ?? conn.database ?? '' };
+	}
+
+	/**
+	 * Determine whether a target is a Joomla database, so writes can be gated.
+	 * Resolution order: in-memory cache → explicit per-connection `joomla` flag
+	 * (authoritative) → persisted sidecar marker (learned on a prior connect) →
+	 * live schema probe for the Joomla signature (`<prefix>extensions` paired with
+	 * `<prefix>assets`). A fresh probe result is persisted as a marker so future
+	 * connects skip the round-trip entirely.
+	 */
+	async detectJoomla(connectionName?: string, database?: string): Promise<JoomlaDetection> {
+		const { key, conn } = getConnection(this.config, connectionName);
+		const schema = database ?? conn.database ?? '';
+		const cacheKey = `${key}::${schema}`;
+		const cached = this.joomlaCache.get(cacheKey);
+		if (cached) return cached;
+
+		// Explicit config flag is authoritative — no probe, and it overrides any marker.
+		if (conn.joomla === true) {
+			return this.cache(cacheKey, { isJoomla: true, prefix: conn.joomlaPrefix ?? null, source: 'config' });
+		}
+		if (conn.joomla === false) {
+			return this.cache(cacheKey, { isJoomla: false, prefix: null, source: 'config' });
+		}
+
+		// Without a resolvable target schema we cannot probe or key a marker.
+		if (!schema) {
+			return this.cache(cacheKey, { isJoomla: false, prefix: null, source: 'none' });
+		}
+
+		// Learned marker from a previous connect — instant, no round-trip.
+		const mKey = markerKey(conn.host, conn.port ?? 3306, schema);
+		const marker = await getMarker(mKey);
+		if (marker) {
+			return this.cache(cacheKey, { isJoomla: marker.joomla, prefix: marker.prefix, source: 'marker' });
+		}
+
+		try {
+			const { rows } = await this.query(
+				"SELECT TABLE_NAME AS name FROM information_schema.TABLES " +
+				"WHERE TABLE_SCHEMA = ? AND TABLE_NAME REGEXP '(extensions|assets)$'",
+				[schema], connectionName,
+			);
+			const names = new Set(rows.map((r) => String((r as Record<string, unknown>).name)));
+			let prefix: string | null = null;
+			for (const name of names) {
+				if (!name.endsWith('extensions')) continue;
+				const candidate = name.slice(0, -'extensions'.length);
+				if (names.has(`${candidate}assets`)) { prefix = candidate; break; }
+			}
+			const verdict: JoomlaDetection = prefix !== null
+				? { isJoomla: true, prefix, source: 'auto' }
+				: { isJoomla: false, prefix: null, source: 'auto' };
+			// Persist what we learned so the next connect just knows.
+			await setMarker(mKey, { joomla: verdict.isJoomla, prefix: verdict.prefix, detectedAt: new Date().toISOString() });
+			return this.cache(cacheKey, verdict);
+		} catch {
+			// Probe failed (permissions, missing schema). Degrade to "none" and do
+			// not cache or persist, so a later successful probe can still classify it.
+			return { isJoomla: false, prefix: null, source: 'none' };
+		}
+	}
+
+	private cache(cacheKey: string, verdict: JoomlaDetection): JoomlaDetection {
+		this.joomlaCache.set(cacheKey, verdict);
+		return verdict;
+	}
+
+	private poolFor(connectionName?: string): Pool {
+		const { key, conn } = getConnection(this.config, connectionName);
+		let pool = this.pools.get(key);
+		if (!pool) {
+			const opts: PoolOptions = {
+				host: conn.host,
+				port: conn.port ?? 3306,
+				user: conn.user,
+				password: conn.password,
+				database: conn.database,
+				connectionLimit: 5,
+				waitForConnections: true,
+				timezone: conn.timezone ?? 'Z',
+				multipleStatements: false,
+			};
+			if (conn.ssl) {
+				// Default to verified TLS. A bare `ssl: true` is never silently
+				// downgraded — callers who must skip verification (trusted internal
+				// hosts with self-signed certs) opt out explicitly via
+				// `ssl: { rejectUnauthorized: false }` in their config.
+				opts.ssl = typeof conn.ssl === 'object'
+					? conn.ssl
+					: { rejectUnauthorized: true };
+			}
+			pool = mysql.createPool(opts);
+			this.pools.set(key, pool);
+			// On first connect, learn (and persist) the Joomla verdict for the
+			// connection's default database so the write-gate knows immediately.
+			// Best-effort and non-blocking — never let it break pool creation.
+			if (conn.database) {
+				void this.detectJoomla(connectionName, conn.database).catch(() => undefined);
+			}
+		}
+		return pool;
+	}
+
+	async query(
+		sql: string,
+		params?: unknown[],
+		connectionName?: string,
+		database?: string,
+	): Promise<{ rows: Record<string, unknown>[]; fields: FieldPacket[] }> {
+		const pool = this.poolFor(connectionName);
+		const p = (params ?? []) as (string | number | null)[];
+		if (database) {
+			const conn = await pool.getConnection();
+			try {
+				await conn.query(`USE \`${database.replace(/`/g, '``')}\``);
+				const [rows, fields] = await conn.query(sql, p);
+				return { rows: rows as Record<string, unknown>[], fields };
+			} finally {
+				conn.release();
+			}
+		}
+		const [rows, fields] = await pool.query(sql, p);
+		return { rows: rows as Record<string, unknown>[], fields };
+	}
+
+	async execute(
+		sql: string,
+		params?: unknown[],
+		connectionName?: string,
+		database?: string,
+	): Promise<{ affectedRows: number; insertId: number; changedRows: number }> {
+		const pool = this.poolFor(connectionName);
+		const p = (params ?? []) as (string | number | null)[];
+		if (database) {
+			const conn = await pool.getConnection();
+			try {
+				await conn.query(`USE \`${database.replace(/`/g, '``')}\``);
+				const [result] = await conn.execute(sql, p);
+				const r = result as ResultSetHeader;
+				return { affectedRows: r.affectedRows ?? 0, insertId: r.insertId ?? 0, changedRows: r.changedRows ?? 0 };
+			} finally {
+				conn.release();
+			}
+		}
+		const [result] = await pool.execute(sql, p);
+		const r = result as ResultSetHeader;
+		return {
+			affectedRows: r.affectedRows ?? 0,
+			insertId: r.insertId ?? 0,
+			changedRows: r.changedRows ?? 0,
+		};
+	}
+
+	async closeAll(): Promise<void> {
+		for (const [, pool] of this.pools) {
+			await pool.end();
+		}
+		this.pools.clear();
+	}
+}

package/source/config.ts

@@ -1,97 +1,104 @@
-/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
- *
- * This file is part of a Moko Consulting project.
- *
- * SPDX-License-Identifier: GPL-3.0-or-later
- *
- * FILE INFORMATION
- * DEFGROUP: mokomysql.Config
- * INGROUP: mokomysql
- * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokomysql-mcp
- * PATH: /src/config.ts
- * VERSION: 01.00.00
- * BRIEF: Configuration loader for MySQL MCP connections
- */
-
-import { readFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
-import { homedir } from 'node:os';
-import type { MySqlConfig, MySqlConnection } from './types.js';
-import { resolveSecretRefs } from './secrets.js';
-
-const CONFIG_FILENAME = '.mcp_mokomysql.json';
-
-/** Absolute path to the active config file (`MYSQL_MCP_CONFIG` or ~/.mcp_mokomysql.json). */
-export function getConfigPath(): string {
-	return process.env.MYSQL_MCP_CONFIG
-		? resolve(process.env.MYSQL_MCP_CONFIG)
-		: resolve(homedir(), CONFIG_FILENAME);
-}
-
-/**
- * Absolute path to the sidecar state file — the MCP-managed learned-marker store.
- * `MYSQL_MCP_STATE` overrides it outright; otherwise it sits beside the config as
- * `<config>.state.json`, so learned state always follows the config that produced it.
- */
-export function getStatePath(): string {
-	if (process.env.MYSQL_MCP_STATE) return resolve(process.env.MYSQL_MCP_STATE);
-	return getConfigPath().replace(/\.json$/i, '') + '.state.json';
-}
-
-export async function loadConfig(): Promise<MySqlConfig> {
-	const config_path = getConfigPath();
-
-	try {
-		const raw = await readFile(config_path, 'utf-8');
-		const parsed = JSON.parse(raw) as Partial<MySqlConfig>;
-
-		// Resolve any "file:<path>" secret references (e.g. passwords in ~/.ssh/tokens).
-		await resolveSecretRefs(parsed);
-
-		if (!parsed.connections || Object.keys(parsed.connections).length === 0) {
-			throw new Error('No connections defined in config');
-		}
-
-		return {
-			connections: parsed.connections,
-			defaultConnection: parsed.defaultConnection ?? Object.keys(parsed.connections)[0],
-		};
-	} catch (err) {
-		const message = err instanceof Error ? err.message : String(err);
-		throw new Error(
-			`Failed to load config from ${config_path}: ${message}\n` +
-			`Create ${config_path} — see config.example.json for format.`,
-		);
-	}
-}
-
-/**
- * Normalize a name for tag matching: lowercase and strip every character
- * that isn't a letter or digit. This makes "moko.live", "moko-live",
- * "Moko Live" and "mokolive" all collapse to the same key.
- */
-export function normalizeTag(value: string): string {
-	return value.toLowerCase().replace(/[^a-z0-9]+/g, '');
-}
-
-export function getConnection(config: MySqlConfig, name?: string): { key: string; conn: MySqlConnection } {
-	const requested = name ?? config.defaultConnection;
-
-	// 1. Exact key match — fast path, preserves prior behavior exactly.
-	const direct = config.connections[requested];
-	if (direct) return { key: requested, conn: direct };
-
-	// 2. Normalized match against connection keys and their tag shortcuts.
-	//    Returns the canonical key, never the alias/tag the caller typed.
-	const target = normalizeTag(requested);
-	for (const [key, conn] of Object.entries(config.connections)) {
-		if (normalizeTag(key) === target) return { key, conn };
-		if (conn.tags?.some((tag) => normalizeTag(tag) === target)) return { key, conn };
-	}
-
-	// 3. Not found — list keys plus their tags so the caller can self-correct.
-	const available = Object.entries(config.connections)
-		.map(([key, conn]) => (conn.tags?.length ? `${key} [${conn.tags.join(', ')}]` : key))
-		.join(', ');
-	throw new Error(`Connection "${requested}" not found. Available: ${available}`);
-}
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ *
+ * This file is part of a Moko Consulting project.
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * FILE INFORMATION
+ * DEFGROUP: mokomysql.Config
+ * INGROUP: mokomysql
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokomysql-mcp
+ * PATH: /src/config.ts
+ * VERSION: 01.00.00
+ * BRIEF: Configuration loader for MySQL MCP connections
+ */
+
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { homedir } from 'node:os';
+import type { MySqlConfig, MySqlConnection } from './types.js';
+import { resolveSecretRefs } from './secrets.js';
+import { migrateInlineSecrets } from './migrate.js';
+
+const CONFIG_FILENAME = '.mcp_mokomysql.json';
+
+/** Absolute path to the active config file (`MYSQL_MCP_CONFIG` or ~/.mcp_mokomysql.json). */
+export function getConfigPath(): string {
+	return process.env.MYSQL_MCP_CONFIG
+		? resolve(process.env.MYSQL_MCP_CONFIG)
+		: resolve(homedir(), CONFIG_FILENAME);
+}
+
+/**
+ * Absolute path to the sidecar state file — the MCP-managed learned-marker store.
+ * `MYSQL_MCP_STATE` overrides it outright; otherwise it sits beside the config as
+ * `<config>.state.json`, so learned state always follows the config that produced it.
+ */
+export function getStatePath(): string {
+	if (process.env.MYSQL_MCP_STATE) return resolve(process.env.MYSQL_MCP_STATE);
+	return getConfigPath().replace(/\.json$/i, '') + '.state.json';
+}
+
+export async function loadConfig(): Promise<MySqlConfig> {
+	const config_path = getConfigPath();
+
+	try {
+		const raw = await readFile(config_path, 'utf-8');
+		const parsed = JSON.parse(raw) as Partial<MySqlConfig>;
+
+		// Self-heal: migrate any INLINE secret (no-inline-secrets policy) to a
+		// file-backed ref and rewrite the config. Warn-only on failure — never
+		// crashes, never loses the credential. Runs before resolveSecretRefs so
+		// the freshly written "file:" refs are resolved below.
+		await migrateInlineSecrets(parsed, config_path);
+
+		// Resolve any "file:<path>" secret references (e.g. passwords in ~/.ssh/tokens).
+		await resolveSecretRefs(parsed);
+
+		if (!parsed.connections || Object.keys(parsed.connections).length === 0) {
+			throw new Error('No connections defined in config');
+		}
+
+		return {
+			connections: parsed.connections,
+			defaultConnection: parsed.defaultConnection ?? Object.keys(parsed.connections)[0],
+		};
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(
+			`Failed to load config from ${config_path}: ${message}\n` +
+			`Create ${config_path} — see config.example.json for format.`,
+		);
+	}
+}
+
+/**
+ * Normalize a name for tag matching: lowercase and strip every character
+ * that isn't a letter or digit. This makes "moko.live", "moko-live",
+ * "Moko Live" and "mokolive" all collapse to the same key.
+ */
+export function normalizeTag(value: string): string {
+	return value.toLowerCase().replace(/[^a-z0-9]+/g, '');
+}
+
+export function getConnection(config: MySqlConfig, name?: string): { key: string; conn: MySqlConnection } {
+	const requested = name ?? config.defaultConnection;
+
+	// 1. Exact key match — fast path, preserves prior behavior exactly.
+	const direct = config.connections[requested];
+	if (direct) return { key: requested, conn: direct };
+
+	// 2. Normalized match against connection keys and their tag shortcuts.
+	//    Returns the canonical key, never the alias/tag the caller typed.
+	const target = normalizeTag(requested);
+	for (const [key, conn] of Object.entries(config.connections)) {
+		if (normalizeTag(key) === target) return { key, conn };
+		if (conn.tags?.some((tag) => normalizeTag(tag) === target)) return { key, conn };
+	}
+
+	// 3. Not found — list keys plus their tags so the caller can self-correct.
+	const available = Object.entries(config.connections)
+		.map(([key, conn]) => (conn.tags?.length ? `${key} [${conn.tags.join(', ')}]` : key))
+		.join(', ');
+	throw new Error(`Connection "${requested}" not found. Available: ${available}`);
+}