@nsyan/db 1.0.0

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@nsyan/db",
+  "version": "1.0.0",
+  "description": "AI 接入数据库扩展 —— 四大家族方言架构，支持 PostgreSQL/MySQL/Oracle/达梦/Redis/Elasticsearch/Hive/Spark，提供查询/表结构/扫描建连工具给 LLM",
+  "keywords": [
+    "pi-extension",
+    "pi-package",
+    "database",
+    "postgresql",
+    "mysql",
+    "oracle",
+    "dameng",
+    "dm",
+    "redis",
+    "elasticsearch",
+    "hive",
+    "spark"
+  ],
+  "license": "MIT",
+  "main": "index.ts",
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "files": [
+    "index.ts",
+    "src/",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./index.ts",
+    "./core": "./src/core/index.ts",
+    "./dialects": "./src/dialects/index.ts"
+  },
+  "dependencies": {
+    "@elastic/elasticsearch": "^9.5.1",
+    "dmdb": "^1.0.52452",
+    "es7": "npm:@elastic/elasticsearch@7",
+    "hive-driver": "^1.0.1",
+    "ioredis": "^6.0.0",
+    "mysql2": "^3.23.1",
+    "oracledb": "^7.0.1",
+    "pg": "^8.22.0"
+  },
+  "devDependencies": {
+    "@types/pg": "^8.20.0",
+    "tsx": "^4.23.13"
+  },
+  "scripts": {
+    "test": "tsx --test \"test/**/*.test.ts\""
+  }
+}

package/src/config.ts

@@ -0,0 +1,220 @@
+// config.ts —— 连接配置与插件配置读写（含旧文件名兼容 + mtime 内存缓存）
+// 注：本模块只做 JSON 文件 IO，不依赖任何 pi 运行时模块
+import { existsSync, readFileSync, writeFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { registry } from "./dialects/index.js";
+import type { ConnConfig, DbTypeId } from "./core/types.js";
+
+// ── 路径 ──────────────────────────────────────────
+
+export const CONFIG_FILE = join(homedir(), ".pi", "agent", "db-configs.json");
+export const PLUGIN_CONFIG_FILE = join(homedir(), ".pi", "agent", "db-config.json");
+const LEGACY_PLUGIN_CONFIG_FILE = join(homedir(), ".pi", "agent", "db-plugin-config.json");
+
+// ── 插件全局配置 ──────────────────────────────────
+
+export interface PluginConfig {
+  /** AI 是否只能执行 SELECT（禁止写入） */
+  ai_readonly: boolean;
+  /** SQL 执行前确认策略: never=不确认 / write=写操作前确认 / always=每次都确认 */
+  confirm_before_exec: "never" | "write" | "always";
+  /** 查询返回的最大行数 */
+  max_rows: number;
+  /** 单条 SQL 超时秒数 */
+  query_timeout: number;
+}
+
+export const DEFAULT_PLUGIN_CONFIG: PluginConfig = {
+  ai_readonly: true,
+  confirm_before_exec: "write",
+  max_rows: 100,
+  query_timeout: 30,
+};
+
+// ── mtime 内存缓存 ────────────────────────────────
+
+// 注：必须用 Map 按文件名 key——单槽缓存在 db-configs.json 与 db-config.json 交替读时永不命中
+const caches = new Map<string, { mtime: number; data: unknown }>();
+
+function readJsonCached<T>(file: string, fallback: T): T {
+  if (!existsSync(file)) return fallback;
+  const mtime = statSync(file).mtimeMs;
+  const hit = caches.get(file);
+  if (hit && hit.mtime === mtime) return hit.data as T;
+  try {
+    const data = JSON.parse(readFileSync(file, "utf-8")) as T;
+    caches.set(file, { mtime, data });
+    return data;
+  } catch { return fallback; }
+}
+
+export function invalidateConfigCache(file?: string): void {
+  if (file) caches.delete(file); else caches.clear();
+}
+
+// ── 连接配置读写（存储态即 ConnConfig[]，Spec §2.0 配置类型裁决）───
+
+interface LegacyStoredConfig extends Record<string, unknown> {
+  extraParams?: Record<string, string>;
+}
+
+function migrateStored(raw: unknown): ConnConfig {
+  const c = raw as LegacyStoredConfig & Partial<ConnConfig>;
+  const { extraParams, ...rest } = c;
+  const out = rest as ConnConfig;
+  // 旧文件 extraParams（历史 DbConfig 字段，代码未使用）并入 options
+  if (extraParams && typeof extraParams === "object") {
+    out.options = { ...(out.options ?? {}), ...extraParams };
+  }
+  return out;
+}
+
+export function loadConfigs(): ConnConfig[] {
+  const raw = readJsonCached<unknown[]>(CONFIG_FILE, []);
+  if (!Array.isArray(raw)) return [];
+  return raw.map(migrateStored);
+}
+
+export function saveConfigs(configs: ConnConfig[]): void {
+  writeFileSync(CONFIG_FILE, JSON.stringify(configs, null, 2));
+  invalidateConfigCache(CONFIG_FILE);
+}
+
+// ── 插件全局配置读写（含旧名 db-plugin-config.json 兼容）───
+
+export function loadPluginConfig(): PluginConfig {
+  if (!existsSync(PLUGIN_CONFIG_FILE)) {
+    // 兼容旧版配置文件名
+    if (existsSync(LEGACY_PLUGIN_CONFIG_FILE)) {
+      try {
+        const raw = JSON.parse(readFileSync(LEGACY_PLUGIN_CONFIG_FILE, "utf-8"));
+        return { ...DEFAULT_PLUGIN_CONFIG, ...raw };
+      } catch {
+        return { ...DEFAULT_PLUGIN_CONFIG };
+      }
+    }
+    return { ...DEFAULT_PLUGIN_CONFIG };
+  }
+  try {
+    const raw = JSON.parse(readFileSync(PLUGIN_CONFIG_FILE, "utf-8"));
+    return { ...DEFAULT_PLUGIN_CONFIG, ...raw };
+  } catch {
+    return { ...DEFAULT_PLUGIN_CONFIG };
+  }
+}
+
+export function savePluginConfig(cfg: PluginConfig): void {
+  writeFileSync(PLUGIN_CONFIG_FILE, JSON.stringify(cfg, null, 2));
+  invalidateConfigCache(PLUGIN_CONFIG_FILE);
+}
+
+export function getConfigSummary(cfg: PluginConfig): string {
+  const readonlyLabel = cfg.ai_readonly ? "是" : "否";
+  const confirmLabel =
+    cfg.confirm_before_exec === "never" ? "不确认" :
+    cfg.confirm_before_exec === "write" ? "写操作确认" : "每次都确认";
+  return [
+    `AI 只读: ${readonlyLabel}`,
+    `执行确认: ${confirmLabel}`,
+    `最大行数: ${cfg.max_rows}`,
+    `查询超时: ${cfg.query_timeout}s`,
+  ].join("\n");
+}
+
+// ── 辅助: 查找数据库配置（忽略大小写和首尾空格） ────
+
+export function findConfig(configs: ConnConfig[], name: string): ConnConfig | undefined {
+  const target = name.trim().toLowerCase();
+  return configs.find((c) => c.name.toLowerCase() === target);
+}
+
+// ── 一键连接串解析（Spec §11.1 P0）──────────────
+// 遍历 registry 各方言 parseUrl，首个非 null 胜出（各方言兼收 JDBC + 原生 URI 双形态，Spec §7）
+
+export interface ParsedConnectionString {
+  dialectId: DbTypeId;
+  host: string;
+  port: number;
+  username?: string;
+  password?: string;
+  database?: string;
+  dbIndex?: number;
+}
+
+export function parseConnectionString(input: string): ParsedConnectionString | null {
+  const url = input.trim();
+  if (!url) return null;
+  for (const d of registry.values()) {
+    const p = d.parseUrl(url);
+    if (!p) continue;
+    // 仅保留有值字段（undefined 键会让 deepEqual 语义变脏，也避免下游覆盖默认值）
+    const out: ParsedConnectionString = { dialectId: d.id, host: p.host, port: p.port };
+    if (p.username !== undefined) out.username = p.username;
+    if (p.password !== undefined) out.password = p.password;
+    if (p.database !== undefined) out.database = p.database;
+    if (p.dbIndex !== undefined) out.dbIndex = p.dbIndex;
+    return out;
+  }
+  return null;
+}
+
+// ── 默认连接（Spec §11.1 P0：database 参数可选，缺省走 isDefault 标记的连接）───
+
+export function getDefaultConfig(configs: ConnConfig[]): ConnConfig | undefined {
+  return configs.find((c) => c.isDefault);
+}
+
+export function setDefaultConfig(configs: ConnConfig[], id: string): ConnConfig[] {
+  return configs.map((c) => ({ ...c, isDefault: c.id === id }));
+}
+
+// ── 查询结果导出（Spec §11.1 P0：长结果落盘不糊上下文）───
+
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { toCsv } from "./core/export.js";
+
+export interface QueryExport {
+  csvPath: string;
+  jsonPath: string;
+}
+
+/** 查询结果落盘 /tmp（CSV + JSON），返回路径；失败抛错由调用方容错 */
+export function writeQueryExport(
+  columns: string[],
+  rows: unknown[][],
+  baseName: string,
+): QueryExport {
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const base = join(tmpdir(), `${baseName}-${stamp}`);
+  const csvPath = `${base}.csv`;
+  const jsonPath = `${base}.json`;
+  writeFileSync(csvPath, toCsv(columns, rows), "utf-8");
+  writeFileSync(jsonPath, JSON.stringify({ columns, rows }, null, 2), "utf-8");
+  return { csvPath, jsonPath };
+}
+
+// ── 运行时兜底（carry-over：替代已删除的 toConnConfig）───
+// ConnConfig.host/port/database 为可选（非关系型家族不用）；关系型 doConnect
+// 要求必填，此处在调用点补齐，保证 undefined 永不流入方言层。
+
+export function toRuntimeConfig(c: ConnConfig, defaultPort: number): ConnConfig {
+  return {
+    ...c,
+    host: c.host || "localhost",
+    port: c.port || defaultPort,
+    username: c.username ?? "",
+    password: c.password ?? "",
+  };
+}
+
+// 供 UI 层展示类型短标签（原 index.ts 内 5 处重复映射的收敛点之一）
+export function shortTypeLabel(type: DbTypeId): string {
+  return ({ postgresql: "PG", mysql: "MySQL", oracle: "Oracle" } as Record<string, string>)[type] ?? type;
+}
+
+export function fullTypeLabel(type: DbTypeId): string {
+  return ({ postgresql: "PostgreSQL", mysql: "MySQL", oracle: "Oracle" } as Record<string, string>)[type] ?? type;
+}

package/src/core/export.ts

@@ -0,0 +1,14 @@
+// core/export.ts —— 查询结果导出纯函数（CSV/JSON 落盘由调用方执行；本模块零依赖可测）
+
+function csvEscape(v: unknown): string {
+  const s = v === null || v === undefined ? "" : String(v);
+  if (/[",\n\r]/.test(s)) return `"${s.replace(/"/g, '""')}"`;
+  return s;
+}
+
+/** 行数据 → CSV 文本（首行表头；含逗号/引号/换行的值按 RFC 4180 转义） */
+export function toCsv(columns: string[], rows: unknown[][]): string {
+  const lines = [columns.map(csvEscape).join(",")];
+  for (const row of rows) lines.push(row.map(csvEscape).join(","));
+  return lines.join("\n");
+}

package/src/core/index.ts

@@ -0,0 +1,7 @@
+// core/index.ts —— core 聚合 re-export（package.json exports "./core" 的入口）
+export type { DbTypeId, DbFamily, ConnConfig, ParsedTarget, DbConnection, ExecOpts,
+  CandidateStatus, Candidate, TableInfo, ColumnInfo, QueryResult, ListTablesResult,
+  DescribeTableResult, TestConnectionResult } from "./types.js";
+export { stripComments, splitStatements, isWriteStatement, isDropStatement } from "./sql-text.js";
+export { decide } from "./policy.js";
+export type { ConfirmMode } from "./policy.js";

package/src/core/policy.ts

@@ -0,0 +1,11 @@
+// core/policy.ts
+import type { Verdict } from "../dialects/dialect.js";
+
+export type ConfirmMode = "never" | "write" | "always";
+
+export function decide(verdict: Verdict, _readonly: boolean, confirm: ConfirmMode): "run" | "confirm" | "deny" {
+  if (!verdict.ok) return "deny";
+  if (confirm === "always") return "confirm";
+  if (confirm === "write" && verdict.isWrite) return "confirm";
+  return "run";
+}

package/src/core/scan/candidates.ts

@@ -0,0 +1,286 @@
+// scan/candidates.ts —— scanProject 组装：walker → parsers → spring/placeholders → scoring → Candidate[]
+// 状态机：ready（可直接测连）/ incomplete（缺字段）/ encrypted（jasypt ENC，只标注不建）/ exists（同名已存在）
+// 红线：绝不静默建连（写盘由 index.ts 向导确认后执行）；密码掩码在输出层（index.ts）做，
+//       本模块的 partial 保留真实值仅供 TUI 补录。
+import { readFileSync } from "node:fs";
+import { basename, dirname, extname, join, relative } from "node:path";
+import { registry } from "../../dialects/index.js";
+import { loadConfigs } from "../../config.js";
+import type { Candidate, ConnConfig, DbTypeId, ParsedTarget } from "../types.js";
+import { resolveRoot, walk } from "./walker.js";
+import { parseCompose, parseEnv, parseProperties, parseSimpleYaml, extractUrls } from "./parsers.js";
+import { springKeysToRaw, profileOf, type RawDbConfig } from "./spring.js";
+import { resolvePlaceholder } from "./placeholders.js";
+import { isExcluded, sourceWeight } from "./scoring.js";
+
+// ── 内部表示 ──────────────────────────────────────
+
+interface FieldBag {
+  host?: string; port?: number;
+  username?: string; password?: string;
+  database?: string; dbIndex?: number;
+  ssl?: boolean;
+  url?: string;
+}
+
+interface RawCand {
+  dialectId: DbTypeId;
+  bag: FieldBag;
+  file: string;
+  profile: string;
+  confidence: number;
+}
+
+// 各家族建连必需字段（missing 的判定依据；空串同样视为缺失）
+const REQUIRED: Record<DbTypeId, string[]> = {
+  postgresql: ["host", "port", "database", "username", "password"],
+  mysql: ["host", "port", "database", "username", "password"],
+  oracle: ["host", "port", "database", "username", "password"],
+  dm: ["host", "port", "database", "username", "password"],
+  hive: ["host", "port", "database", "username"],
+  spark: ["host", "port", "database", "username"],
+  redis: ["host", "port", "password"],
+  elasticsearch: ["host", "port"],
+};
+
+// ── 工具函数 ──────────────────────────────────────
+
+function flattenYaml(node: unknown, prefix = "", out: Record<string, string> = {}): Record<string, string> {
+  if (node && typeof node === "object" && !Array.isArray(node)) {
+    for (const [k, v] of Object.entries(node as Record<string, unknown>)) {
+      flattenYaml(v, prefix ? `${prefix}.${k}` : k, out);
+    }
+  } else if (typeof node === "string" || typeof node === "number") {
+    out[prefix] = String(node);
+  }
+  return out;
+}
+
+function toInt(v: unknown): number | undefined {
+  const n = typeof v === "number" ? v : parseInt(String(v), 10);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+function stripQuery(url: string): string {
+  return url.split(/[?#]/)[0];
+}
+
+/** 遍历 registry 各方言 parseUrl，首个非 null 胜出（与 index.ts parseDbUrl 同一模式）。 */
+function parseUrlViaRegistry(url: string): ({ dialectId: DbTypeId } & ParsedTarget) | null {
+  for (const d of registry.values()) {
+    const p = d.parseUrl(url);
+    if (p) return { dialectId: d.id, ...p };
+  }
+  return null;
+}
+
+function dialectFromImage(image: string): DbTypeId | null {
+  const i = image.toLowerCase();
+  if (/postgres/.test(i)) return "postgresql";
+  if (/(^|\/)(mysql|mariadb)/.test(i)) return "mysql";
+  if (/redis/.test(i)) return "redis";
+  if (/elasticsearch/.test(i)) return "elasticsearch";
+  if (/dm8|dameng/.test(i)) return "dm";
+  if (/hive/.test(i)) return "hive";
+  return null;
+}
+
+/** 同目录 .env 缓存（${KEY} 无 default 时的第二优先级） */
+function loadDirEnv(file: string, cache: Map<string, Record<string, string> | undefined>): Record<string, string> | undefined {
+  const dir = dirname(file);
+  if (cache.has(dir)) return cache.get(dir);
+  let env: Record<string, string> | undefined;
+  try {
+    env = parseEnv(readFileSync(join(dir, ".env"), "utf-8"));
+  } catch { env = undefined; }
+  cache.set(dir, env);
+  return env;
+}
+
+// ── 主流程 ────────────────────────────────────────
+
+export async function scanProject(
+  rootInput: string,
+  opts?: { existingNames?: string[] },
+): Promise<Candidate[]> {
+  const root = resolveRoot(rootInput); // 越界直接抛（红线）
+  const files = walk(root);
+  const raws: RawCand[] = [];
+  const dirEnvCache = new Map<string, Record<string, string> | undefined>();
+
+  const pushUrl = (url: string, file: string, profile: string, confidence: number, keyFields?: Partial<RawDbConfig>): void => {
+    const parsed = parseUrlViaRegistry(stripQuery(url));
+    if (!parsed) return;
+    raws.push({
+      dialectId: parsed.dialectId,
+      // URL 内嵌账号密码与 spring 键字段合并：显式键（spring.datasource.username/password）优先
+      bag: {
+        url,
+        host: parsed.host,
+        port: parsed.port,
+        username: keyFields?.username ?? parsed.username,
+        password: keyFields?.password ?? parsed.password,
+        database: parsed.database,
+        dbIndex: parsed.dbIndex,
+        ssl: parsed.ssl,
+      },
+      file, profile, confidence,
+    });
+  };
+
+  const pushRaw = (raw: RawDbConfig): void => {
+    if (raw.url) {
+      pushUrl(raw.url, raw.file, raw.profile, raw.weight, raw);
+      return;
+    }
+    // 无 URL 的键式候选：redis/es 可凭 host 判定；关系型无 URL 无法建连，跳过
+    let dialectId: DbTypeId | null = null;
+    if (raw.group === "redis" && raw.host) dialectId = "redis";
+    else if (raw.group === "es" && raw.host) dialectId = "elasticsearch";
+    if (!dialectId) return;
+    raws.push({
+      dialectId,
+      bag: { host: raw.host, port: toInt(raw.port), username: raw.username, password: raw.password, dbIndex: toInt(raw.dbIndex) },
+      file: raw.file, profile: raw.profile, confidence: raw.weight,
+    });
+  };
+
+  for (const file of files) {
+    const rel = relative(root, file).split("\\").join("/");
+    if (isExcluded(rel)) continue;
+    const ext = extname(file).toLowerCase();
+    const base = basename(file).toLowerCase();
+    let text: string;
+    try { text = readFileSync(file, "utf-8"); } catch { continue; }
+    if (text.length > 512 * 1024) continue; // 大文件跳过
+
+    const weight = sourceWeight(rel);
+    const profile = profileOf(base);
+
+    if (base === ".env" || base.startsWith(".env.")) {
+      const env = parseEnv(text);
+      for (const [k, v] of Object.entries(env)) {
+        if (/(^|_)(DATABASE_URL|DATASOURCE_URL|REDIS_URL|ELASTICSEARCH_URL|DB_URL|JDBC_URL)$|_URL$/i.test(k)) {
+          pushUrl(v, file, profile, weight);
+        }
+      }
+      continue;
+    }
+
+    if (ext === ".yml" || ext === ".yaml") {
+      if (base.startsWith("docker-compose") || base.startsWith("compose")) {
+        for (const svc of parseCompose(text)) {
+          const dialectId = svc.image ? dialectFromImage(svc.image) : null;
+          if (!dialectId) continue;
+          const bag: FieldBag = {
+            host: svc.name, // compose 网络内服务名即主机名
+            port: hostPortOf(svc.ports),
+            username: svc.env["POSTGRES_USER"] ?? svc.env["MYSQL_USER"] ?? svc.env["ES_USERNAME"],
+            password: svc.env["POSTGRES_PASSWORD"] ?? svc.env["MYSQL_ROOT_PASSWORD"] ?? svc.env["MYSQL_PASSWORD"] ?? svc.env["REDIS_PASSWORD"] ?? svc.env["ELASTIC_PASSWORD"],
+            database: svc.env["POSTGRES_DB"] ?? svc.env["MYSQL_DATABASE"],
+          };
+          raws.push({ dialectId, bag, file, profile, confidence: weight });
+          // compose 里也可能带完整 Spring URL
+          for (const [k, v] of Object.entries(svc.env)) {
+            if (/URL$/.test(k)) pushUrl(v, file, profile, weight);
+          }
+        }
+      } else {
+        const dotted = flattenYaml(parseSimpleYaml(text));
+        for (const raw of springKeysToRaw(dotted, file, weight)) pushRaw(raw);
+      }
+    } else if (ext === ".properties") {
+      const dotted = parseProperties(text);
+      for (const raw of springKeysToRaw(dotted, file, weight)) pushRaw(raw);
+    }
+
+    // 通用 URL 正则全文件扫（兜底，低权重）
+    for (const url of extractUrls(text)) pushUrl(url, file, profile, 0.5);
+  }
+
+  // ── 占位符解析 + 状态机 ──────────────────────────
+  const projectName = basename(root);
+  const existingNames = new Set(opts?.existingNames ?? loadConfigs().map((c) => c.name));
+
+  const resolved: RawCand[] = [];
+  const seen = new Map<string, number>(); // dedupe key → index in resolved
+  for (const raw of raws) {
+    const env = loadDirEnv(raw.file, dirEnvCache);
+    const bag: FieldBag = {};
+    for (const [k, v] of Object.entries(raw.bag)) {
+      if (v === undefined) continue;
+      if (typeof v !== "string") { (bag as Record<string, unknown>)[k] = v; continue; }
+      const r = resolvePlaceholder(v, env);
+      if (r.resolved) (bag as Record<string, unknown>)[k] = r.value;
+      // 未解析的占位符：字段从 bag 消失 → 落入 missing
+    }
+
+    // 去重：同一实例（dialect|host|port|database）只保留一条；
+    // 后到的低置信度候选（如同文件通用 URL 兆底）把自身字段补入已有候选（凭据增强），不新增
+    const key = `${raw.dialectId}|${bag.host ?? ""}|${bag.port ?? ""}|${bag.database ?? ""}`;
+    const prevIdx = seen.get(key);
+    if (prevIdx !== undefined) {
+      const prev = resolved[prevIdx];
+      if (raw.confidence > prev.confidence) {
+        prev.confidence = raw.confidence;
+        prev.profile = raw.profile;
+      }
+      for (const [k, v] of Object.entries(bag)) {
+        if ((prev.bag as Record<string, unknown>)[k] === undefined && v !== undefined) {
+          (prev.bag as Record<string, unknown>)[k] = v;
+        }
+      }
+      continue;
+    }
+    seen.set(key, resolved.length);
+    resolved.push({ ...raw, bag });
+  }
+
+  // 确定性输出：置信度降序 → 默认名升序（同名多 profile 时 default 在前，消费方 find 可预期）
+  const nameOf = (r: RawCand): string => `${projectName}-${r.profile}-${r.dialectId}`;
+  resolved.sort((a, b) => b.confidence - a.confidence || nameOf(a).localeCompare(nameOf(b)));
+
+  const candidates: Candidate[] = resolved.map((raw) => {
+    const defaultName = `${projectName}-${raw.profile}-${raw.dialectId}`;
+    const missing: string[] = [];
+    for (const f of REQUIRED[raw.dialectId]) {
+      const v = (raw.bag as Record<string, unknown>)[f];
+      if (v === undefined || v === "") missing.push(f);
+    }
+    let status: Candidate["status"];
+    const pwd = raw.bag.password;
+    if (typeof pwd === "string" && pwd.startsWith("ENC(")) {
+      status = "encrypted";
+    } else if (existingNames.has(defaultName)) {
+      status = "exists";
+    } else if (missing.length === 0) {
+      status = "ready";
+    } else {
+      status = "incomplete";
+    }
+    const partial: Partial<ConnConfig> = {
+      name: defaultName,
+      type: raw.dialectId,
+      ...raw.bag,
+    };
+    return {
+      status,
+      dialectId: raw.dialectId,
+      partial,
+      missing,
+      source: { file: raw.file, profile: raw.profile, confidence: raw.confidence },
+    };
+  });
+
+  return candidates;
+}
+
+/** compose 端口映射取主机侧端口："5432:5432" → 5432；"127.0.0.1:5432:5432" → 5432 */
+function hostPortOf(ports: string[]): number | undefined {
+  for (const p of ports) {
+    const parts = p.split(":");
+    const n = parseInt(parts[parts.length - 2] ?? parts[0], 10);
+    if (Number.isFinite(n)) return n;
+  }
+  return undefined;
+}