@carllee1983/dbcli 1.28.0 → 1.29.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

@@ -81222,7 +81222,7 @@ var {
 // package.json
 var package_default = {
   name: "@carllee1983/dbcli",
-  version: "1.28.0",
+  version: "1.29.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
  */
@@ -2789,6 +2789,15 @@ export declare function listConnections(config: DbcliConfigV2): Array<{
 	};
 	isDefault: boolean;
 }>;
+export declare function resolveConfigStoragePath(path: string): Promise<string>;
+/**
+ * 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 {
@@ -9312,10 +9316,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"]);
@@ -9569,7 +9819,6 @@ function inferColumnType(value) {
 
 // src/core/public.ts
 init_schema_loader();
-
 // src/core/blacklist-manager.ts
 class BlacklistManager {
   config;
@@ -9737,9 +9986,14 @@ class BlacklistValidator {
     });
   }
 }
+
+// src/core/public.ts
+var readConfig = (path, connectionName) => configModule.read(path, connectionName);
 export {
   resolveConnection,
+  resolveConfigStoragePath,
   readV2Config,
+  readConfig,
   loadConnectionEnv,
   listConnections,
   detectConfigVersion,

package/package.json

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