@yejiming/dsh-data-agent 0.0.9 → 0.0.11

package/lib/{connections-DeauhaZi.js → connections-5sfdEDsG.js}

@@ -1,5 +1,7 @@
 import "./defaults-DP4RyRh1.js";
-import { resolve } from "node:path";
+import { readdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { posix, resolve, win32 } from "node:path";
 import z from "schemastery";
 import { credentialRef } from "@deepseek-ai/dsh-credentials";
 //#region src/sql.ts
@@ -595,7 +597,8 @@ function quoteStringLiteral(value) {
 /** Loader schema for one client override (all fields optional at input). */
 const clientConfigSchema = z.object({
 	command: z.string(),
-	args: z.array(z.string())
+	args: z.array(z.string()),
+	searchPaths: z.array(z.string())
 });
 /** Loader schema for the whole `clients` config object (any type key). */
 const clientsSchema = z.dict(clientConfigSchema).default({});
@@ -891,6 +894,291 @@ function parseColumns(type, stdout) {
 	return columns;
 }
 //#endregion
+//#region src/client-discovery.ts
+/**
+* Cross-platform database CLI discovery.
+*
+* The subprocess provider remains the authority for executable validation.
+* This module only builds a bounded, platform-aware PATH fallback when the
+* provider cannot resolve the configured/default bare command from its
+* current execution environment. No shell, registry, or recursive scan is
+* involved, and the exact discovery environment is returned for spawn.
+* @module @yejiming/dsh-data-agent/client-discovery
+*/
+/** Maximum child names consumed from one known version/formula directory. */
+const MAX_DYNAMIC_ENTRIES = 64;
+/** Production host facts. */
+const DEFAULT_SYSTEM = {
+	platform: process.platform,
+	env: process.env,
+	homeDir: homedir(),
+	cwd: process.cwd(),
+	async readDirectory(directory) {
+		return await readdir(directory);
+	}
+};
+const HOME_ENV_BY_TYPE = {
+	mysql: ["MYSQL_HOME"],
+	postgres: ["PGHOME", "PGROOT"],
+	sqlite: ["SQLITE_HOME"],
+	oracle: ["ORACLE_HOME"],
+	hive: ["HIVE_HOME"],
+	impala: ["IMPALA_HOME"]
+};
+function pathApi(platform) {
+	return platform === "win32" ? win32 : posix;
+}
+function environmentValue(env, name, platform) {
+	if (platform !== "win32") return env[name];
+	const key = Object.keys(env).find((candidate) => candidate.toLowerCase() === name.toLowerCase());
+	return key === void 0 ? void 0 : env[key];
+}
+function expandHome(directory, system, paths) {
+	const trimmed = directory.trim();
+	if (trimmed === "~") return system.homeDir;
+	if (trimmed.startsWith("~/") || trimmed.startsWith("~\\")) return paths.join(system.homeDir, trimmed.slice(2));
+	return paths.isAbsolute(trimmed) ? paths.normalize(trimmed) : paths.resolve(system.cwd, trimmed);
+}
+function normalizeDirectories(directories, system, paths) {
+	const result = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const raw of directories) {
+		if (raw.trim() === "") continue;
+		const directory = expandHome(raw, system, paths);
+		const key = system.platform === "win32" ? directory.toLowerCase() : directory;
+		if (seen.has(key)) continue;
+		seen.add(key);
+		result.push(directory);
+	}
+	return result;
+}
+function clientHomeDirectories(type, system, paths) {
+	const result = [];
+	for (const name of HOME_ENV_BY_TYPE[type]) {
+		const value = environmentValue(system.env, name, system.platform)?.trim();
+		if (value === void 0 || value === "") continue;
+		result.push(paths.join(value, "bin"), value);
+	}
+	return result;
+}
+function macFixedDirectories(type) {
+	return [
+		"/opt/homebrew/bin",
+		...{
+			mysql: [
+				"/opt/homebrew/opt/mysql-client/bin",
+				"/opt/homebrew/opt/mysql/bin",
+				"/usr/local/opt/mysql-client/bin",
+				"/usr/local/opt/mysql/bin",
+				"/usr/local/mysql/bin"
+			],
+			postgres: [
+				"/opt/homebrew/opt/libpq/bin",
+				"/usr/local/opt/libpq/bin",
+				"/Applications/Postgres.app/Contents/Versions/latest/bin"
+			],
+			sqlite: ["/opt/homebrew/opt/sqlite/bin", "/usr/local/opt/sqlite/bin"],
+			oracle: [],
+			hive: ["/opt/homebrew/opt/hive/bin", "/usr/local/opt/hive/bin"],
+			impala: ["/opt/homebrew/opt/impala/bin", "/usr/local/opt/impala/bin"]
+		}[type],
+		"/usr/local/bin",
+		"/opt/local/bin",
+		"/usr/bin"
+	];
+}
+function linuxFixedDirectories(system, paths) {
+	return [
+		paths.join(system.homeDir, ".local", "bin"),
+		"/home/linuxbrew/.linuxbrew/bin",
+		paths.join(system.homeDir, ".linuxbrew", "bin"),
+		"/usr/local/bin",
+		"/usr/bin",
+		"/snap/bin",
+		paths.join(system.homeDir, ".nix-profile", "bin"),
+		"/nix/var/nix/profiles/default/bin"
+	];
+}
+function windowsFixedDirectories(type, system, paths) {
+	const localAppData = environmentValue(system.env, "LOCALAPPDATA", system.platform);
+	const userProfile = environmentValue(system.env, "USERPROFILE", system.platform) ?? system.homeDir;
+	const chocolatey = environmentValue(system.env, "ChocolateyInstall", system.platform);
+	const programData = environmentValue(system.env, "ProgramData", system.platform) ?? "C:\\ProgramData";
+	const programFiles = environmentValue(system.env, "ProgramFiles", system.platform) ?? "C:\\Program Files";
+	const typeSpecific = {
+		mysql: [],
+		postgres: [],
+		sqlite: [paths.join("C:\\", "sqlite"), paths.join(programFiles, "SQLite")],
+		oracle: [],
+		hive: [],
+		impala: []
+	};
+	return [
+		...localAppData === void 0 ? [] : [paths.join(localAppData, "Microsoft", "WinGet", "Links")],
+		paths.join(userProfile, "scoop", "shims"),
+		...chocolatey === void 0 ? [] : [paths.join(chocolatey, "bin")],
+		paths.join(programData, "chocolatey", "bin"),
+		...typeSpecific[type]
+	];
+}
+function formulaPattern(type) {
+	switch (type) {
+		case "mysql": return /^(?:mysql|mysql-client)(?:@.+)?$/i;
+		case "postgres": return /^(?:postgresql(?:@.+)?|libpq)$/i;
+		case "sqlite": return /^sqlite(?:@.+)?$/i;
+		case "oracle": return /^(?:oracle|instantclient)(?:@.+)?$/i;
+		case "hive": return /^hive(?:@.+)?$/i;
+		case "impala": return /^impala(?:@.+)?$/i;
+	}
+}
+function dynamicDirectories(type, system, paths) {
+	const result = [];
+	if (system.platform === "darwin") {
+		const pattern = formulaPattern(type);
+		result.push({
+			root: "/opt/homebrew/opt",
+			accepts: (name) => pattern.test(name),
+			suffix: ["bin"]
+		}, {
+			root: "/usr/local/opt",
+			accepts: (name) => pattern.test(name),
+			suffix: ["bin"]
+		});
+		if (type === "postgres") result.push({
+			root: "/Library/PostgreSQL",
+			accepts: () => true,
+			suffix: ["bin"]
+		}, {
+			root: "/Applications/Postgres.app/Contents/Versions",
+			accepts: (name) => name !== "latest",
+			suffix: ["bin"]
+		});
+		if (type === "oracle") result.push({
+			root: "/opt/oracle",
+			accepts: (name) => /^instantclient/i.test(name),
+			suffix: []
+		});
+	} else if (system.platform === "linux") {
+		const pattern = formulaPattern(type);
+		result.push({
+			root: "/home/linuxbrew/.linuxbrew/opt",
+			accepts: (name) => pattern.test(name),
+			suffix: ["bin"]
+		}, {
+			root: paths.join(system.homeDir, ".linuxbrew", "opt"),
+			accepts: (name) => pattern.test(name),
+			suffix: ["bin"]
+		});
+	} else if (system.platform === "win32") {
+		const roots = [environmentValue(system.env, "ProgramFiles", system.platform) ?? "C:\\Program Files", environmentValue(system.env, "ProgramFiles(x86)", system.platform) ?? "C:\\Program Files (x86)"];
+		for (const root of roots) if (type === "mysql") result.push({
+			root: paths.join(root, "MySQL"),
+			accepts: () => true,
+			suffix: ["bin"]
+		}, {
+			root,
+			accepts: (name) => /^MariaDB/i.test(name),
+			suffix: ["bin"]
+		});
+		else if (type === "postgres") result.push({
+			root: paths.join(root, "PostgreSQL"),
+			accepts: () => true,
+			suffix: ["bin"]
+		});
+		else if (type === "oracle") result.push({
+			root: paths.join(root, "Oracle"),
+			accepts: () => true,
+			suffix: ["bin"]
+		});
+	}
+	return result;
+}
+async function expandDynamicDirectories(descriptors, system, paths, signal) {
+	return (await Promise.all(descriptors.map(async (descriptor) => {
+		signal.throwIfAborted();
+		let names;
+		try {
+			names = await system.readDirectory(descriptor.root);
+		} catch {
+			return [];
+		}
+		signal.throwIfAborted();
+		return names.filter((name) => descriptor.accepts(name)).sort((left, right) => right.localeCompare(left, void 0, {
+			numeric: true,
+			sensitivity: "base"
+		})).slice(0, MAX_DYNAMIC_ENTRIES).map((name) => paths.join(descriptor.root, name, ...descriptor.suffix));
+	}))).flat();
+}
+/** Build ordered fallback directories without recursively scanning the host. */
+async function buildClientSearchDirectories(type, config, signal, system = DEFAULT_SYSTEM) {
+	const paths = pathApi(system.platform);
+	const configured = config?.searchPaths ?? [];
+	const homes = clientHomeDirectories(type, system, paths);
+	const fixed = system.platform === "win32" ? windowsFixedDirectories(type, system, paths) : system.platform === "darwin" ? macFixedDirectories(type) : linuxFixedDirectories(system, paths);
+	const dynamic = await expandDynamicDirectories(dynamicDirectories(type, system, paths), system, paths, signal);
+	signal.throwIfAborted();
+	return normalizeDirectories([
+		...configured,
+		...homes,
+		...fixed,
+		...dynamic
+	], system, paths);
+}
+function hasPathSeparator(command) {
+	return command.includes("/") || command.includes("\\");
+}
+function withSearchPath(explicitEnv, directories, system) {
+	const pathName = system.platform === "win32" ? Object.keys(system.env).find((name) => name.toLowerCase() === "path") ?? "Path" : "PATH";
+	const explicitPathName = Object.keys(explicitEnv).find((name) => system.platform === "win32" ? name.toLowerCase() === "path" : name === "PATH");
+	const parentPath = explicitPathName === void 0 ? environmentValue(system.env, "PATH", system.platform) : explicitEnv[explicitPathName];
+	const separator = system.platform === "win32" ? ";" : ":";
+	const prefix = directories.join(separator);
+	const combined = parentPath === void 0 || parentPath === "" ? prefix : `${prefix}${separator}${parentPath}`;
+	const result = { ...explicitEnv };
+	if (explicitPathName !== void 0 && explicitPathName !== pathName) delete result[explicitPathName];
+	result[pathName] = combined;
+	return result;
+}
+function errorText(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function checkedDirectoriesText(directories) {
+	const visible = directories.slice(0, 16);
+	const suffix = directories.length > visible.length ? `，另有${directories.length - visible.length}个目录` : "";
+	return visible.length === 0 ? "无补充目录" : `${visible.join("、")}${suffix}`;
+}
+/**
+* Resolve one configured/default client. Current PATH (or an explicit path)
+* always wins. Only a missing bare command activates bounded PATH discovery.
+*/
+async function resolveClientExecutable(options) {
+	const system = options.system ?? DEFAULT_SYSTEM;
+	let initialError;
+	try {
+		return {
+			executable: await options.resolveExecutable(options.command, options.env, options.signal),
+			env: options.env,
+			searchedDirectories: []
+		};
+	} catch (error) {
+		options.signal.throwIfAborted();
+		initialError = error;
+	}
+	if (pathApi(system.platform).isAbsolute(options.command) || hasPathSeparator(options.command)) throw new Error(`无法解析数据库客户端 "${options.command}"（类型 ${options.type}：${errorText(initialError)}）；该显式路径不会回退到默认命令，请检查 clients.${options.type}.command`);
+	const directories = await buildClientSearchDirectories(options.type, options.config, options.signal, system);
+	const discoveryEnv = withSearchPath(options.env, directories, system);
+	try {
+		return {
+			executable: await options.resolveExecutable(options.command, discoveryEnv, options.signal),
+			env: discoveryEnv,
+			searchedDirectories: directories
+		};
+	} catch (fallbackError) {
+		options.signal.throwIfAborted();
+		throw new Error(`无法解析数据库客户端 "${options.command}"（类型 ${options.type}；当前PATH：${errorText(initialError)}；补充PATH：${errorText(fallbackError)}）。已检查：${checkedDirectoriesText(directories)}；请确认客户端已安装，或配置 clients.${options.type}.command / clients.${options.type}.searchPaths`);
+	}
+}
+//#endregion
 //#region src/query.ts
 /** Read one collected stream from offset 0. */
 function readCaptured(reader) {
@@ -934,15 +1222,16 @@ async function runClientQuery(ctx, connection, sql, options, externalSignal, int
 	if (externalSignal.aborted) controller.abort(externalSignal.reason);
 	else externalSignal.addEventListener("abort", onExternalAbort, { once: true });
 	try {
-		let executable;
-		try {
-			executable = await ctx.subprocess.resolveExecutable(template.command, template.env, controller.signal);
-		} catch (error) {
-			controller.signal.throwIfAborted();
-			throw new Error(`无法解析数据库客户端 "${template.command}"（${error instanceof Error ? error.message : String(error)}）；请确认客户端已安装，或在 data-agent 插件配置的 clients 中覆盖命令名/路径`);
-		}
+		const resolution = await resolveClientExecutable({
+			type: connection.type,
+			command: template.command,
+			config: options.clients[connection.type],
+			env: template.env,
+			signal: controller.signal,
+			resolveExecutable: ctx.subprocess.resolveExecutable.bind(ctx.subprocess)
+		});
 		const handle = ctx.subprocess.spawn({
-			argv: [executable, ...template.args],
+			argv: [resolution.executable, ...template.args],
 			cwd: process.cwd(),
 			stdio: {
 				stdin: { data: `${template.stdinPrefix}${sql}\n` },
@@ -951,7 +1240,7 @@ async function runClientQuery(ctx, connection, sql, options, externalSignal, int
 			},
 			graceMs: options.graceMs ?? 5e3,
 			signal: controller.signal,
-			env: template.env
+			env: resolution.env
 		});
 		let outcome;
 		try {
@@ -1016,7 +1305,8 @@ function normalizeConnectionInput(input, cwd = process.cwd()) {
 	if (input.name !== void 0 && input.name.trim().length === 0) throw new Error("name 不能为空");
 	const connection = {
 		type: input.type,
-		database: input.type === "sqlite" ? resolve(cwd, input.database) : input.database
+		database: input.type === "sqlite" ? resolve(cwd, input.database) : input.database,
+		credentialMode: input.type === "sqlite" ? "none" : input.passwordRef !== void 0 ? "reference" : input.password !== void 0 && input.password.length > 0 ? "password" : "none"
 	};
 	if (input.type !== "sqlite") {
 		if (input.host !== void 0 && input.host.length > 0) connection.host = input.host;
@@ -1057,16 +1347,21 @@ function createConnectionService(ctx, options, persistence) {
 		return ctx;
 	};
 	const resolveCredential = async (connection) => {
-		if (connection.passwordRef === void 0) return {
-			...connection,
-			tables: copyTables(connection.tables)
-		};
-		const ref = validatedCredentialRef(connection.passwordRef);
-		const hit = await requireContext().credentials.resolve(ref);
-		if (hit === void 0 || hit.value.length === 0) throw new Error(`凭据引用 "${connection.passwordRef}" 未配置`);
+		const mode = credentialModeOf(connection);
+		if (mode === "reference") {
+			if (connection.passwordRef === void 0) throw new Error("数据库凭据引用缺失，请重新配置连接");
+			const ref = validatedCredentialRef(connection.passwordRef);
+			const hit = await requireContext().credentials.resolve(ref);
+			if (hit === void 0 || hit.value.length === 0) throw new Error(`凭据引用 "${connection.passwordRef}" 未配置`);
+			return {
+				...connection,
+				password: hit.value,
+				tables: copyTables(connection.tables)
+			};
+		}
+		if (mode === "password" && connection.password === void 0) throw new Error("数据库凭据需要重新输入；请打开数据库配置并重新连接");
 		return {
 			...connection,
-			password: hit.value,
 			tables: copyTables(connection.tables)
 		};
 	};
@@ -1111,18 +1406,29 @@ function createConnectionService(ctx, options, persistence) {
 		}
 	};
 	const credentialSummary = async (connection) => {
-		if (connection.type === "sqlite") return void 0;
-		if (connection.password !== void 0) return {
+		const mode = credentialModeOf(connection);
+		if (connection.type === "sqlite" || mode === "none") return void 0;
+		if (mode === "password") return connection.password === void 0 ? { configured: false } : {
 			configured: true,
 			source: "memory"
 		};
-		if (connection.passwordRef === void 0) return { configured: false };
+		if (mode !== "reference" || connection.passwordRef === void 0) return { configured: false };
 		const info = await requireContext().credentials.describe(validatedCredentialRef(connection.passwordRef));
 		return {
 			configured: info.configured,
 			...info.source !== void 0 ? { source: info.source } : {}
 		};
 	};
+	const statusSummary = async (connection) => {
+		const summary = summarize(connection);
+		const mode = credentialModeOf(connection);
+		summary.credentialMode = mode;
+		summary.credential = await credentialSummary(connection);
+		const ready = mode === "none" || summary.credential?.configured === true;
+		summary.ready = ready;
+		summary.reconnectRequired = !ready;
+		return summary;
+	};
 	const service = {
 		set(sessionId, connection) {
 			if (connection.password !== void 0 && connection.passwordRef !== void 0) throw new Error("password 与 passwordRef 不能同时提供");
@@ -1165,9 +1471,7 @@ function createConnectionService(ctx, options, persistence) {
 		async status(sessionId) {
 			const connection = rawConnection(sessionId);
 			if (connection === void 0) return void 0;
-			const summary = summarize(connection);
-			summary.credential = await credentialSummary(connection);
-			return summary;
+			return statusSummary(connection);
 		},
 		async connect(sessionId, input, signal) {
 			if (sessionId.length === 0) throw new Error("sessionId 必须是非空字符串");
@@ -1183,11 +1487,9 @@ function createConnectionService(ctx, options, persistence) {
 				tables
 			};
 			runtime.set(sessionId, published);
-			const summary = summarize(published);
-			summary.credential = await credentialSummary(published);
 			return {
 				tables,
-				summary
+				summary: await statusSummary(published)
 			};
 		},
 		async disconnect(sessionId) {
@@ -1202,11 +1504,9 @@ function createConnectionService(ctx, options, persistence) {
 				tables
 			};
 			runtime.set(sessionId, published);
-			const summary = summarize(published);
-			summary.credential = await credentialSummary(published);
 			return {
 				tables,
-				summary
+				summary: await statusSummary(published)
 			};
 		},
 		async resolveForExecution(sessionId) {
@@ -1294,7 +1594,8 @@ function connectionFromProfile(profileId, profile) {
 		...profile.port !== void 0 ? { port: profile.port } : {},
 		...profile.user !== void 0 ? { user: profile.user } : {},
 		...profile.readonly !== void 0 ? { readonly: profile.readonly } : {},
-		...profile.passwordRef !== void 0 ? { passwordRef: profile.passwordRef } : {}
+		...profile.passwordRef !== void 0 ? { passwordRef: profile.passwordRef } : {},
+		credentialMode: profile.credentialMode ?? (profile.type === "sqlite" ? "none" : profile.passwordRef !== void 0 ? "reference" : "password")
 	};
 }
 function profileFromConnection(connection, updatedAt) {
@@ -1307,9 +1608,18 @@ function profileFromConnection(connection, updatedAt) {
 		...connection.port !== void 0 ? { port: connection.port } : {},
 		...connection.user !== void 0 ? { user: connection.user } : {},
 		...connection.readonly !== void 0 ? { readonly: connection.readonly } : {},
-		...connection.passwordRef !== void 0 ? { passwordRef: connection.passwordRef } : {}
+		...connection.passwordRef !== void 0 ? { passwordRef: connection.passwordRef } : {},
+		...connection.credentialMode !== void 0 ? { credentialMode: connection.credentialMode } : {}
 	};
 }
+/** Infer legacy records while leaving ambiguous secret-less SQL profiles conservative. */
+function credentialModeOf(connection) {
+	if (connection.credentialMode !== void 0) return connection.credentialMode;
+	if (connection.type === "sqlite") return "none";
+	if (connection.passwordRef !== void 0) return "reference";
+	if (connection.password !== void 0) return "password";
+	return "none";
+}
 function requireIdentifier(type, value, label) {
 	if (value === void 0 || value.length === 0) throw new Error(`${label} 不能为空`);
 	sanitizeIdentifier(type, value);