@carllee1983/dbcli 1.28.0 → 1.30.0

package/CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to dbcli are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.29.0] - 2026-06-08 - Core Config-Read Entrypoint
+
+### Added
+
+- **`@carllee1983/dbcli/core` 新增設定載入入口。** 在 `./core` 子路徑公開 `readConfig(path, connectionName?)`（binding-aware、v1/v2、`{$env}` 展開的統一設定讀取，與 CLI 指令同源）、`resolveConfigStoragePath(path)`（project-binding 解參）與型別 `DbcliConfigV2`、`SqlConnectionOptions`／`QueryableConnectionOptions`（SQL adapter 連線型別收窄）。讓外部消費者（如 `dbcli-gui` sidecar）能從 `.dbcli` 專案路徑解出含真實連線資訊的 `DbcliConfig`，不必重寫內部 binding／env 邏輯。CLI 行為不變。
+
 ## [1.28.0] - 2026-06-08 - Core Subpath Export
 
 ### Added

package/dist/cli.mjs

@@ -7136,9 +7136,11 @@ async function writeV2Config(path, config) {
   DbcliConfigV2Schema.parse(config);
   const storagePath = await resolveConfigStoragePath(path);
   const configPath = join2(storagePath, "config.json");
+  const tmpPath = `${configPath}.tmp`;
   await Bun.$`mkdir -p ${storagePath}`;
   const json = JSON.stringify(config, null, 2);
-  await Bun.write(configPath, json);
+  await Bun.write(tmpPath, json);
+  await Bun.$`mv -f ${tmpPath} ${configPath}`;
 }
 async function patchConnectionSchema(dbcliPath, connectionName, schema, metadataUpdate) {
   const storagePath = await resolveConfigStoragePath(dbcliPath);
@@ -81222,7 +81224,7 @@ var {
 // package.json
 var package_default = {
   name: "@carllee1983/dbcli",
-  version: "1.28.0",
+  version: "1.30.0",
   description: "Database CLI for AI agents",
   type: "module",
   publishConfig: {

package/dist/core.d.ts

@@ -44,10 +44,10 @@ export interface ConnectionOptions {
 	/** Whether to reject unauthorized TLS connections (default: true) */
 	rejectUnauthorized?: boolean;
 }
-type SqlConnectionOptions = ConnectionOptions & {
+export type SqlConnectionOptions = ConnectionOptions & {
 	system: SqlDatabaseSystem;
 };
-type QueryableConnectionOptions = ConnectionOptions & {
+export type QueryableConnectionOptions = ConnectionOptions & {
 	system: QueryableDatabaseSystem;
 };
 /**
@@ -2516,7 +2516,7 @@ declare const DbcliConfigV2Schema: z.ZodEffects<z.ZodObject<{
 	} | undefined;
 	schemas?: Record<string, Record<string, any>> | undefined;
 }>;
-type DbcliConfigV2 = z.infer<typeof DbcliConfigV2Schema>;
+export type DbcliConfigV2 = z.infer<typeof DbcliConfigV2Schema>;
 /**
  * QueryExecutor class for executing SQL queries with permission checks
  */
@@ -2769,6 +2769,12 @@ export declare function loadConnectionEnv(resolved: ResolvedConnection, basePath
  * Read and validate a v2 config from disk
  */
 export declare function readV2Config(path: string): Promise<DbcliConfigV2>;
+/**
+ * Write a v2 config to disk atomically (temp file + rename).
+ * Writing to a temp file then renaming over the target is an atomic operation
+ * on the same filesystem, so a crash mid-write can never leave a corrupt config.
+ */
+export declare function writeV2Config(path: string, config: DbcliConfigV2): Promise<void>;
 /**
  * List all connection names in a v2 config
  */
@@ -2789,6 +2795,55 @@ export declare function listConnections(config: DbcliConfigV2): Array<{
 	};
 	isDefault: boolean;
 }>;
+export type SqlSystem = "postgresql" | "mysql" | "mariadb";
+/**
+ * `$env` 變數名。per-connection 命名空間化:常駐 sidecar 共用 process.env,
+ * 且 loadEnvFile 不覆寫既有 key——若兩連線都用 DB_PASSWORD 會撞名取到對方的值。
+ */
+export declare function envVarNameFor(connName: string, field: "password"): string;
+/** 把 secret 寫進該連線的 envFile(KEY=VALUE);既有同名 key 就地覆寫,否則追加。 */
+export declare function writeConnectionSecret(projectPath: string, connName: string, field: "password", value: string): Promise<void>;
+export interface ConnectionInput {
+	name: string;
+	system: SqlSystem;
+	host: string;
+	port: number;
+	user: string;
+	database: string;
+}
+/** 刪除連線(immutable)。刪預設則改派為剩餘第一條;刪最後一條則擋下(v2 需至少一條)。 */
+export declare function removeConnection(config: DbcliConfigV2, name: string): DbcliConfigV2;
+/** 設定預設連線(immutable)。 */
+export declare function setDefaultConnection(config: DbcliConfigV2, name: string): DbcliConfigV2;
+/**
+ * v1 單連線 → v2,產生唯一 'default' 連線。沿用 v1 既有密碼慣例:legacy
+ * `.env.local` 的 `DB_PASSWORD`,故 default 連線 envFile 指向 '.env.local'、
+ * password 設 {$env:'DB_PASSWORD'},不搬動既有 secret。blacklist/audit/metadata 原樣帶過。
+ */
+export declare function migrateV1ToV2(v1: DbcliConfig$1): DbcliConfigV2;
+/** 新增或就地覆寫同名連線(immutable)。非機密欄存字面值,password 存 {$env} 參照 +
+ *  per-connection envFile。編輯時保留既有 permission;新建預設 'query-only'。 */
+export declare function upsertConnection(config: DbcliConfigV2, input: ConnectionInput): DbcliConfigV2;
+interface ProjectConfigBinding {
+	version: 3;
+	binding: {
+		type: "home-storage";
+		storagePath: string;
+		projectPath: string;
+		createdAt: string;
+	};
+}
+export declare function getProjectStoragePath(projectPath: string): string;
+export declare function resolveConfigStoragePath(path: string): Promise<string>;
+export declare function writeProjectBinding(projectPath: string, storagePath?: string): Promise<ProjectConfigBinding>;
+/**
+ * Read and fully resolve a `.dbcli` project config: handles project-binding
+ * indirection, v1/v2 formats, per-connection `.env` loading and `{$env}`
+ * expansion. `path` is the `.dbcli` directory (or legacy file). Returns the
+ * default config if none exists. Thin wrapper over the same entrypoint the
+ * CLI commands use.
+ */
+export declare const readConfig: (path: string, connectionName?: string) => Promise<DbcliConfig$1>;
 
 export {
 	DbcliConfig$1 as DbcliConfig,

package/dist/core.mjs

@@ -976,6 +976,10 @@ var init_schema_index = __esm(() => {
 });
 
 // src/core/schema-loader.ts
+var exports_schema_loader = {};
+__export(exports_schema_loader, {
+  SchemaLayeredLoader: () => SchemaLayeredLoader
+});
 import { join as join8 } from "path";
 
 class SchemaLayeredLoader {
@@ -5081,6 +5085,7 @@ class SessionIdService {
 }
 
 // src/core/config-binding.ts
+import { createHash } from "crypto";
 import { homedir } from "os";
 import { basename, join as join3, resolve } from "path";
 var BINDING_FILE_NAME = "config.json";
@@ -5091,6 +5096,15 @@ function isProjectConfigBinding(raw) {
   const candidate = raw;
   return candidate.version === 3 && typeof candidate.binding === "object" && candidate.binding !== null && candidate.binding.type === "home-storage" && typeof candidate.binding.storagePath === "string" && candidate.binding.storagePath.length > 0 && typeof candidate.binding.projectPath === "string" && candidate.binding.projectPath.length > 0 && typeof candidate.binding.createdAt === "string" && candidate.binding.createdAt.length > 0;
 }
+function getDbcliHomeRoot() {
+  return DBCLI_HOME_ROOT;
+}
+function getProjectStoragePath(projectPath) {
+  const normalizedProjectPath = resolve(projectPath);
+  const projectName = basename(normalizedProjectPath) || "project";
+  const hash = createHash("sha1").update(normalizedProjectPath).digest("hex").slice(0, 12);
+  return join3(getDbcliHomeRoot(), "projects", `${projectName}-${hash}`);
+}
 async function readProjectBinding(projectPath) {
   const configFile = Bun.file(join3(projectPath, BINDING_FILE_NAME));
   if (!await configFile.exists())
@@ -5106,6 +5120,21 @@ async function resolveConfigStoragePath(path) {
   const binding = await readProjectBinding(path);
   return binding?.binding.storagePath ?? path;
 }
+async function writeProjectBinding(projectPath, storagePath = getProjectStoragePath(projectPath)) {
+  const binding = {
+    version: 3,
+    binding: {
+      type: "home-storage",
+      storagePath,
+      projectPath: resolve(projectPath),
+      createdAt: new Date().toISOString()
+    }
+  };
+  await Bun.$`mkdir -p ${projectPath}`;
+  await Bun.$`mkdir -p ${storagePath}`;
+  await Bun.file(join3(projectPath, BINDING_FILE_NAME)).write(JSON.stringify(binding, null, 2));
+  return binding;
+}
 
 // node_modules/zod/v3/external.js
 var exports_external = {};
@@ -9296,6 +9325,16 @@ async function readV2Config(path) {
   const raw = JSON.parse(content);
   return DbcliConfigV2Schema.parse(raw);
 }
+async function writeV2Config(path, config) {
+  DbcliConfigV2Schema.parse(config);
+  const storagePath = await resolveConfigStoragePath(path);
+  const configPath = join4(storagePath, "config.json");
+  const tmpPath = `${configPath}.tmp`;
+  await Bun.$`mkdir -p ${storagePath}`;
+  const json = JSON.stringify(config, null, 2);
+  await Bun.write(tmpPath, json);
+  await Bun.$`mv -f ${tmpPath} ${configPath}`;
+}
 function listConnections(config) {
   return Object.entries(config.connections).map(([name, conn]) => {
     const c = conn;
@@ -9312,10 +9351,256 @@ function listConnections(config) {
 }
 
 // src/core/config.ts
+import { join as join9 } from "path";
 var _globalConnectionName;
 function getGlobalConnectionName() {
   return _globalConnectionName;
 }
+var DEFAULT_CONFIG = {
+  connection: {
+    system: "postgresql",
+    host: "localhost",
+    port: 5432,
+    user: "",
+    password: "",
+    database: ""
+  },
+  permission: "query-only",
+  schema: {},
+  metadata: {
+    version: "1.0"
+  },
+  blacklist: { tables: [], columns: {} },
+  audit: {
+    enabled: true,
+    rotation: { max_bytes: 10485760, max_entries: 1000 }
+  }
+};
+function isEnvReference(value) {
+  return typeof value === "object" && value !== null && "$env" in value && typeof value.$env === "string";
+}
+function resolveEnvReferences(config, env, parentKey, strict = false) {
+  if (isEnvReference(config)) {
+    const envKey = config.$env;
+    const value = env[envKey];
+    if (!value) {
+      if (!strict) {
+        return config;
+      }
+      throw new ConfigError(`Environment variable not defined: ${envKey}
+` + `Please set ${envKey} in .env or your environment.
+` + `Hint: check your .env file or run 'export ${envKey}=<value>'`);
+    }
+    if (parentKey === "port") {
+      const portNum = parseInt(value, 10);
+      if (isNaN(portNum) || portNum < 1 || portNum > 65535) {
+        throw new ConfigError(`${envKey} must be a valid port number (1-65535), got: ${value}`);
+      }
+      return portNum;
+    }
+    return value;
+  }
+  if (Array.isArray(config)) {
+    return config.map((item) => resolveEnvReferences(item, env, parentKey, strict));
+  }
+  if (typeof config === "object" && config !== null) {
+    const resolved = {};
+    for (const [key, value] of Object.entries(config)) {
+      resolved[key] = resolveEnvReferences(value, env, key, strict);
+    }
+    return resolved;
+  }
+  return config;
+}
+function parseEnvPassword(content) {
+  const match = content.match(/^DBCLI_PASSWORD=(.+)$/m);
+  return match?.[1] != null ? match[1].trim() : null;
+}
+var configModule = {
+  async read(path, connectionName) {
+    const effectiveConnectionName = connectionName ?? _globalConnectionName;
+    try {
+      const binding = await readProjectBinding(path);
+      const storagePath = await resolveConfigStoragePath(path);
+      if (binding) {
+        const storageConfigExists = await Bun.file(join9(storagePath, "config.json")).exists();
+        if (!storageConfigExists) {
+          throw new ConfigError(`Bound dbcli config not found: ${join9(storagePath, "config.json")}`);
+        }
+      }
+      let isDirectory = false;
+      try {
+        const stat3 = await Bun.file(storagePath).stat();
+        isDirectory = stat3?.isDirectory() ?? false;
+      } catch {
+        isDirectory = false;
+      }
+      if (isDirectory) {
+        const configPath = join9(storagePath, "config.json");
+        const configFile = Bun.file(configPath);
+        const configExists = await configFile.exists();
+        if (configExists) {
+          const content = await configFile.text();
+          const config = JSON.parse(content);
+          if (detectConfigVersion(config) === 2) {
+            const v2Config = DbcliConfigV2Schema.parse(config);
+            const resolved = resolveConnection(v2Config, effectiveConnectionName);
+            await loadConnectionEnv(resolved, storagePath);
+            const envLocalPath = join9(storagePath, ".env.local");
+            const envLocalFile = Bun.file(envLocalPath);
+            let legacyPassword = null;
+            if (await envLocalFile.exists()) {
+              const envContent = await envLocalFile.text();
+              legacyPassword = parseEnvPassword(envContent);
+              if (legacyPassword && !process.env.DBCLI_PASSWORD) {
+                process.env.DBCLI_PASSWORD = legacyPassword;
+              }
+            }
+            const resolvedConnection = resolveEnvReferences(resolved.connection, process.env, undefined, false);
+            if (!resolvedConnection.password && legacyPassword) {
+              resolvedConnection.password = legacyPassword;
+            }
+            let schema = (v2Config.schemas ?? {})[resolved.name] ?? v2Config.schema;
+            try {
+              const { SchemaLayeredLoader: SchemaLayeredLoader2 } = await Promise.resolve().then(() => (init_schema_loader(), exports_schema_loader));
+              const loader = new SchemaLayeredLoader2(storagePath, { connectionName: resolved.name });
+              const { cache, index } = await loader.initialize();
+              if (index && Object.keys(index.tables).length > 0) {
+                const layeredSchema = {};
+                for (const tableName of Object.keys(index.tables)) {
+                  const s = await cache.getTableSchema(tableName);
+                  if (s)
+                    layeredSchema[tableName] = s;
+                }
+                if (Object.keys(layeredSchema).length > 0) {
+                  schema = layeredSchema;
+                }
+              }
+            } catch {
+              console.warn("Warning: Failed to load layered schema cache, falling back to config.json");
+            }
+            return DbcliConfigSchema.parse({
+              connection: resolvedConnection,
+              permission: resolved.permission,
+              schema,
+              metadata: v2Config.metadata,
+              blacklist: v2Config.blacklist,
+              audit: v2Config.audit,
+              redis: v2Config.redis
+            });
+          }
+          const resolvedConfig = resolveEnvReferences(config, process.env, undefined, false);
+          const envPath = join9(storagePath, ".env.local");
+          const envFile = Bun.file(envPath);
+          if (await envFile.exists()) {
+            const envContent = await envFile.text();
+            const password = parseEnvPassword(envContent);
+            if (password && !resolvedConfig.connection.password) {
+              resolvedConfig.connection.password = password;
+            }
+          }
+          return DbcliConfigSchema.parse(resolvedConfig);
+        }
+      }
+      const file = Bun.file(path);
+      const exists = await file.exists();
+      if (exists) {
+        const content = await file.text();
+        const raw = JSON.parse(content);
+        const resolved = resolveEnvReferences(raw, process.env, undefined, false);
+        return DbcliConfigSchema.parse(resolved);
+      }
+      return { ...DEFAULT_CONFIG };
+    } catch (error) {
+      if (error instanceof ConfigError)
+        throw error;
+      if (error instanceof Error && error.message.includes("JSON")) {
+        throw new ConfigError(`Failed to parse .dbcli file: ${error.message}`);
+      }
+      throw new ConfigError(`Failed to read .dbcli config: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  },
+  validate(raw) {
+    try {
+      return DbcliConfigSchema.parse(raw);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new ConfigError(`Invalid .dbcli config structure: ${errorMessage}`);
+    }
+  },
+  merge(existing, updates) {
+    const mergedConfig = {
+      ...existing,
+      ...updates,
+      connection: {
+        ...existing.connection,
+        ...updates.connection || {}
+      },
+      schema: {
+        ...existing.schema,
+        ...updates.schema || {}
+      },
+      metadata: {
+        ...existing.metadata,
+        ...updates.metadata || {},
+        createdAt: existing.metadata?.createdAt || new Date().toISOString(),
+        version: existing.metadata?.version || "1.0"
+      }
+    };
+    return mergedConfig;
+  },
+  async write(path, config) {
+    try {
+      this.validate(config);
+      const storagePath = await resolveConfigStoragePath(path);
+      let isDirectory = false;
+      try {
+        const stat3 = await Bun.file(storagePath).stat();
+        isDirectory = stat3?.isDirectory() ?? false;
+      } catch {
+        isDirectory = false;
+      }
+      if (isDirectory || path.endsWith(".dbcli") || path === storagePath && isDirectory) {
+        await Bun.$`mkdir -p ${storagePath}`;
+        const hasEnvReferences = isEnvReference(config.connection.password);
+        if (hasEnvReferences) {
+          const configPath = join9(storagePath, "config.json");
+          const configJson = JSON.stringify(config, null, 2);
+          await Bun.file(configPath).write(configJson);
+        } else {
+          const password = config.connection.password;
+          const configWithoutPassword = {
+            ...config,
+            connection: {
+              ...config.connection,
+              password: undefined
+            }
+          };
+          delete configWithoutPassword.connection.password;
+          const configPath = join9(storagePath, "config.json");
+          const configJson = JSON.stringify(configWithoutPassword, null, 2);
+          await Bun.file(configPath).write(configJson);
+          if (password) {
+            const envPath = join9(storagePath, ".env.local");
+            const envContent = `# Database Credentials - DO NOT commit to git
+
+DBCLI_PASSWORD=${password}
+`;
+            await Bun.file(envPath).write(envContent);
+          }
+        }
+      } else {
+        const json = JSON.stringify(config, null, 2);
+        await Bun.file(path).write(json);
+      }
+    } catch (error) {
+      if (error instanceof ConfigError) {
+        throw error;
+      }
+      throw new ConfigError(`Failed to write .dbcli config: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+};
 
 // src/utils/redaction.ts
 var SQL_SUBCOMMANDS = new Set(["query", "export"]);
@@ -9570,6 +9855,104 @@ function inferColumnType(value) {
 // src/core/public.ts
 init_schema_loader();
 
+// src/core/config-v2-mutations.ts
+import { join as join10 } from "path";
+var SQL_SYSTEMS = ["postgresql", "mysql", "mariadb"];
+function envVarNameFor(connName, field) {
+  const slug = connName.toUpperCase().replace(/[^A-Z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+  return `DBCLI_${slug}_${field.toUpperCase()}`;
+}
+async function writeConnectionSecret(projectPath, connName, field, value) {
+  if (value.includes(`
+`) || value.includes("\r")) {
+    throw new Error("secret value \u4E0D\u53EF\u5305\u542B\u63DB\u884C\u5B57\u5143");
+  }
+  const config = await readV2Config(projectPath);
+  const conn = config.connections[connName];
+  if (!conn)
+    throw new Error(`\u9023\u7DDA '${connName}' \u4E0D\u5B58\u5728`);
+  const storagePath = await resolveConfigStoragePath(projectPath);
+  const envFile = conn.envFile ?? `.env.${connName}`;
+  const envPath = join10(storagePath, envFile);
+  const varName = envVarNameFor(connName, field);
+  let content = "";
+  const file = Bun.file(envPath);
+  if (await file.exists())
+    content = await file.text();
+  const line = `${varName}=${value}`;
+  const re = new RegExp(`^${varName}=.*$`, "m");
+  if (re.test(content)) {
+    content = content.replace(re, line);
+  } else {
+    content = content.length && !content.endsWith(`
+`) ? `${content}
+${line}
+` : `${content}${line}
+`;
+  }
+  await Bun.write(envPath, content);
+}
+function removeConnection(config, name) {
+  if (!(name in config.connections))
+    throw new Error(`\u9023\u7DDA '${name}' \u4E0D\u5B58\u5728`);
+  const rest = { ...config.connections };
+  delete rest[name];
+  const remaining = Object.keys(rest);
+  if (remaining.length === 0)
+    throw new Error("\u7121\u6CD5\u522A\u9664\u6700\u5F8C\u4E00\u689D\u9023\u7DDA");
+  const nextDefault = config.default === name ? remaining[0] : config.default;
+  return { ...config, connections: rest, default: nextDefault };
+}
+function setDefaultConnection(config, name) {
+  if (!(name in config.connections))
+    throw new Error(`\u9023\u7DDA '${name}' \u4E0D\u5B58\u5728`);
+  return { ...config, default: name };
+}
+function migrateV1ToV2(v1) {
+  const system = v1.connection.system;
+  if (!SQL_SYSTEMS.includes(system)) {
+    throw new Error(`v1\u2192v2 \u81EA\u52D5\u5347\u7D1A\u76EE\u524D\u50C5\u652F\u63F4 SQL \u9023\u7DDA(mysql/postgresql/mariadb),\u4E0D\u652F\u63F4 '${system}'`);
+  }
+  const c = v1.connection;
+  return {
+    version: 2,
+    default: "default",
+    connections: {
+      default: {
+        system: c.system,
+        host: c.host,
+        port: c.port,
+        user: c.user,
+        database: c.database,
+        password: { $env: "DB_PASSWORD" },
+        permission: v1.permission ?? "query-only",
+        envFile: ".env.local"
+      }
+    },
+    schema: {},
+    schemas: {},
+    metadata: v1.metadata ?? { version: "2.0" },
+    blacklist: v1.blacklist ?? { tables: [], columns: {} },
+    audit: v1.audit ?? { enabled: true, rotation: { max_bytes: 10485760, max_entries: 1000 } }
+  };
+}
+function upsertConnection(config, input) {
+  const existing = config.connections[input.name];
+  const connection = {
+    system: input.system,
+    host: input.host,
+    port: input.port,
+    user: input.user,
+    database: input.database,
+    password: { $env: envVarNameFor(input.name, "password") },
+    permission: existing?.permission ?? "query-only",
+    envFile: `.env.${input.name}`
+  };
+  return {
+    ...config,
+    connections: { ...config.connections, [input.name]: connection }
+  };
+}
 // src/core/blacklist-manager.ts
 class BlacklistManager {
   config;
@@ -9737,11 +10120,25 @@ class BlacklistValidator {
     });
   }
 }
+
+// src/core/public.ts
+var readConfig = (path, connectionName) => configModule.read(path, connectionName);
 export {
+  writeV2Config,
+  writeProjectBinding,
+  writeConnectionSecret,
+  upsertConnection,
+  setDefaultConnection,
   resolveConnection,
+  resolveConfigStoragePath,
+  removeConnection,
   readV2Config,
+  readConfig,
+  migrateV1ToV2,
   loadConnectionEnv,
   listConnections,
+  getProjectStoragePath,
+  envVarNameFor,
   detectConfigVersion,
   SchemaLayeredLoader,
   QueryExecutor,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carllee1983/dbcli",
-  "version": "1.28.0",
+  "version": "1.30.0",
   "description": "Database CLI for AI agents",
   "type": "module",
   "publishConfig": {