easy-pg-mcp 1.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chenkumi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,228 @@
+# easy-pg-mcp
+
+A lightweight [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that lets AI assistants inspect and query a PostgreSQL database through a safe, structured tool interface.
+
+This project uses Node.js, TypeScript, the official MCP SDK, and [`pg`](https://www.npmjs.com/package/pg) / node-postgres. It runs over stdio, so it can be used directly by MCP clients such as Claude Desktop, Codex, and OpenCode.
+
+## Features
+
+- PostgreSQL connection pooling powered by node-postgres
+- Read-only query tool for data retrieval
+- Execute tool for data modification statements
+- Batch execution and CSV import/export helpers
+- Schema discovery tools for tables, views, indexes, and triggers
+- Query plan inspection with `EXPLAIN`
+- Current user and table grant inspection
+- Optional policy hook and approval workflow
+
+## Requirements
+
+- Node.js 18 or newer
+- npm
+- A reachable PostgreSQL database
+
+## Installation
+
+Run the server directly with `npx`:
+
+```bash
+npx -y easy-pg-mcp
+```
+
+For local development:
+
+```bash
+cd easy-pg-mcp
+npm install
+npm run build
+```
+
+## Configuration
+
+| Variable | Required | Default | Description |
+| --- | --- | --- | --- |
+| `PG_CONNECTION_STRING` | No | - | PostgreSQL connection string. When set, host/user/password/database fields are optional |
+| `PG_HOST` | Yes* | - | PostgreSQL host name or IP address |
+| `PG_PORT` | No | `5432` | PostgreSQL port |
+| `PG_USER` | Yes* | - | PostgreSQL user name |
+| `PG_PASSWORD` | Yes* | - | PostgreSQL password |
+| `PG_DATABASE` | Yes* | - | Database name |
+| `PG_CONNECTION_LIMIT` | No | `10` | Maximum number of active pool connections |
+| `PG_IDLE_TIMEOUT` | No | `30000` | Idle connection timeout in milliseconds |
+| `PG_ENABLE_KEEP_ALIVE` | No | `true` | Whether TCP keep-alive is enabled |
+| `PG_KEEP_ALIVE_INITIAL_DELAY` | No | `0` | Initial TCP keep-alive delay in milliseconds |
+| `PG_SSL` | No | - | Set `true` to enable SSL, or `no-verify` to disable certificate verification |
+| `PG_READ_ONLY` | No | `false` | When `true`, write tools are not registered |
+| `PG_MCP_MODE` | No | `readwrite` | Use `readonly` to disable write execution |
+| `PG_MCP_ALLOW_TABLES` | No | - | Comma-separated table allowlist, such as `users,orders` |
+| `PG_MCP_DENY_TABLES` | No | - | Comma-separated table denylist, such as `payments,secrets` |
+| `PG_BATCH_MAX_SIZE` | No | `100` | Maximum number of parameter sets per internal batch for `pg_batch_execute` |
+| `PG_LOG_PATH` | No | `logs` | Directory used for batch execution and CSV import log files |
+| `PG_POLICY_HOOK` | No | - | HTTP POST URL for external accept/reject/approval policy decisions |
+| `PG_APPROVAL_TTL_SECONDS` | No | `300` | Number of seconds a pending approval remains valid |
+
+`*` Required unless `PG_CONNECTION_STRING` is set.
+
+Example `.env`:
+
+```env
+PG_HOST=localhost
+PG_PORT=5432
+PG_USER=postgres
+PG_PASSWORD=your_password
+PG_DATABASE=your_database
+```
+
+## MCP Client Examples
+
+Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "easy-pg-mcp": {
+      "command": "npx",
+      "args": ["-y", "easy-pg-mcp"],
+      "env": {
+        "PG_HOST": "localhost",
+        "PG_PORT": "5432",
+        "PG_USER": "YOUR USERNAME",
+        "PG_PASSWORD": "YOUR PASSWORD",
+        "PG_DATABASE": "YOUR DB NAME"
+      }
+    }
+  }
+}
+```
+
+Codex `config.toml`:
+
+```toml
+[mcp_servers.easy-pg-mcp]
+args = ["-y", "easy-pg-mcp"]
+command = "npx"
+enabled = true
+
+[mcp_servers.easy-pg-mcp.env]
+PG_HOST = "localhost"
+PG_PORT = "5432"
+PG_USER = "YOUR USERNAME"
+PG_PASSWORD = "YOUR PASSWORD"
+PG_DATABASE = "YOUR DB NAME"
+```
+
+## Available Tools
+
+| Tool | Description |
+| --- | --- |
+| `pg_query` | Execute a read-only SQL query, such as `SELECT` |
+| `pg_execute` | Execute a data modification statement, such as `INSERT`, `UPDATE`, or `DELETE` |
+| `pg_batch_execute` | Execute one data modification statement repeatedly with multiple parameter sets |
+| `pg_import_csv` | Import a UTF-8 CSV file into a table using the header row as column names |
+| `pg_export_csv` | Export all rows from a table to a UTF-8 CSV file |
+| `explain_query` | Run `EXPLAIN` for a `SELECT` query |
+| `list_tables` | List base tables in the current schema, including approximate row counts and comments |
+| `list_views` | List views in the current schema |
+| `describe_table` | Show column information for one or more tables |
+| `describe_index` | Show indexes for a table |
+| `list_triggers` | List triggers in the current schema |
+| `get_current_privileges` | Show the current PostgreSQL user and table grants |
+| `pg_run_approved_command` | Run a pending command after approval, only registered when `PG_POLICY_HOOK` is set |
+| `pg_list_pending_approvals` | List pending approval requests, only registered when `PG_POLICY_HOOK` is set |
+| `pg_cancel_approval` | Cancel a pending approval request, only registered when `PG_POLICY_HOOK` is set |
+
+When `PG_READ_ONLY=true` or `PG_MCP_MODE=readonly`, `pg_execute`, `pg_batch_execute`, and `pg_import_csv` are not registered.
+
+## Parameter Syntax
+
+node-postgres uses positional placeholders: `$1`, `$2`, `$3`, and so on. Do not use MySQL-style `?` placeholders.
+
+Example `pg_execute` input:
+
+```json
+{
+  "sql": "UPDATE users SET email = $1 WHERE id = $2",
+  "params": ["new@example.com", 123]
+}
+```
+
+Example `pg_batch_execute` input:
+
+```json
+{
+  "sql": "INSERT INTO users (name, email) VALUES ($1, $2)",
+  "paramsList": [
+    ["Alice", "alice@example.com"],
+    ["Bob", "bob@example.com"]
+  ],
+  "transaction": "all"
+}
+```
+
+## Batch Execute
+
+`pg_batch_execute` runs the same parameterized write statement with multiple parameter arrays. The `transaction` option controls transaction scope:
+
+| Value | Behavior |
+| --- | --- |
+| `all` | Default. Wrap all rows in one transaction |
+| `batch` | Wrap each internal batch in its own transaction |
+| `each` | Wrap each parameter set in its own transaction |
+| `none` | Do not start explicit transactions |
+
+Detailed per-row execution results are written to a timestamped `.log` file under `PG_LOG_PATH`, which defaults to `logs/`. Log files older than seven days are cleaned up automatically when the server starts.
+
+## SQL Policy
+
+- `pg_query` allows only single-statement `SELECT`, `SHOW`, and `EXPLAIN` queries.
+- `explain_query` accepts only a single `SELECT` statement and runs `EXPLAIN` for it.
+- `pg_execute` allows only single-statement `INSERT`, `UPDATE`, and `DELETE` statements when write mode is enabled.
+- `pg_batch_execute` and `pg_import_csv` use the same write policy as `pg_execute`.
+- `pg_export_csv` checks table policy before exporting table data.
+- Multi-statement SQL is rejected.
+- `SELECT ... INTO` and locking reads are rejected for read-query tools.
+- `PG_MCP_DENY_TABLES` rejects matching tables before `PG_MCP_ALLOW_TABLES` is evaluated.
+- If `PG_MCP_ALLOW_TABLES` is set, every detected table must be included in the allowlist.
+
+Table policy matching is best-effort and based on SQL parsing. PostgreSQL grants remain the final security boundary.
+
+## Policy Hook and Approvals
+
+When `PG_POLICY_HOOK` is configured, the server posts each tool action to the hook after built-in policy checks pass and before the command runs. The hook must return one of:
+
+```json
+{ "status": "accept" }
+```
+
+```json
+{ "status": "reject", "message": "Writes are blocked outside maintenance windows." }
+```
+
+```json
+{ "status": "approval_required", "message": "User approval is required before updating users." }
+```
+
+For `approval_required`, the server stores the pending command in memory and returns an `approvalId`. The MCP host can later call `pg_run_approved_command` with that approval id. Pending approvals are one-time use and expire after `PG_APPROVAL_TTL_SECONDS`.
+
+## Development
+
+```bash
+npm run build
+npm run test
+```
+
+To run the integration tests against a real PostgreSQL database, create `.env`:
+
+```env
+TEST_HOST=localhost
+TEST_PORT=5432
+TEST_USERNAME=test_user
+TEST_PASSWORD=test_password
+TEST_DB=test_database
+```
+
+The tests create and drop temporary tables, a view, a function, and a trigger in `TEST_DB`. If the `TEST_*` variables are missing, integration tests are skipped.
+
+## License
+
+MIT. See [LICENSE.md](LICENSE.md).

package/README.zh-TW.md

@@ -0,0 +1,228 @@
+# easy-pg-mcp
+
+`easy-pg-mcp` 是一個輕量的 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server，讓 AI 助理可以透過安全、結構化的工具介面查詢與檢視 PostgreSQL 資料庫。
+
+本專案使用 Node.js、TypeScript、官方 MCP SDK，以及 [`pg`](https://www.npmjs.com/package/pg) / node-postgres。Server 透過 stdio 運作，可由 Claude Desktop、Codex、OpenCode 等 MCP client 啟動。
+
+## 功能
+
+- 使用 node-postgres 的 PostgreSQL connection pool
+- 唯讀查詢工具
+- INSERT / UPDATE / DELETE 執行工具
+- 批次執行與 CSV 匯入 / 匯出
+- 資料表、view、index、trigger 結構查詢
+- `EXPLAIN` 查詢計畫分析
+- 目前使用者與 table grant 查詢
+- 可選的 policy hook 與 approval workflow
+
+## 需求
+
+- Node.js 18 以上
+- npm
+- 可連線的 PostgreSQL 資料庫
+
+## 安裝
+
+直接用 `npx` 啟動：
+
+```bash
+npx -y easy-pg-mcp
+```
+
+本機開發：
+
+```bash
+cd easy-pg-mcp
+npm install
+npm run build
+```
+
+## 設定
+
+| 變數 | 必填 | 預設值 | 說明 |
+| --- | --- | --- | --- |
+| `PG_CONNECTION_STRING` | 否 | - | PostgreSQL connection string。設定後可省略 host/user/password/database |
+| `PG_HOST` | 是* | - | PostgreSQL host |
+| `PG_PORT` | 否 | `5432` | PostgreSQL port |
+| `PG_USER` | 是* | - | PostgreSQL 使用者 |
+| `PG_PASSWORD` | 是* | - | PostgreSQL 密碼 |
+| `PG_DATABASE` | 是* | - | 資料庫名稱 |
+| `PG_CONNECTION_LIMIT` | 否 | `10` | pool 最大連線數 |
+| `PG_IDLE_TIMEOUT` | 否 | `30000` | idle timeout，單位毫秒 |
+| `PG_ENABLE_KEEP_ALIVE` | 否 | `true` | 是否啟用 TCP keep-alive |
+| `PG_KEEP_ALIVE_INITIAL_DELAY` | 否 | `0` | keep-alive 初始延遲，單位毫秒 |
+| `PG_SSL` | 否 | - | 設為 `true` 啟用 SSL，或 `no-verify` 關閉憑證驗證 |
+| `PG_READ_ONLY` | 否 | `false` | 設為 `true` 時不註冊寫入工具 |
+| `PG_MCP_MODE` | 否 | `readwrite` | 設為 `readonly` 可停用寫入工具 |
+| `PG_MCP_ALLOW_TABLES` | 否 | - | table allowlist，例如 `users,orders` |
+| `PG_MCP_DENY_TABLES` | 否 | - | table denylist，例如 `payments,secrets` |
+| `PG_BATCH_MAX_SIZE` | 否 | `100` | `pg_batch_execute` 每批最大參數組數 |
+| `PG_LOG_PATH` | 否 | `logs` | 批次執行與 CSV 匯入 log 目錄 |
+| `PG_POLICY_HOOK` | 否 | - | 外部 policy hook HTTP POST URL |
+| `PG_APPROVAL_TTL_SECONDS` | 否 | `300` | pending approval 有效秒數 |
+
+`*` 若已設定 `PG_CONNECTION_STRING`，則不必另外設定。
+
+`.env` 範例：
+
+```env
+PG_HOST=localhost
+PG_PORT=5432
+PG_USER=postgres
+PG_PASSWORD=your_password
+PG_DATABASE=your_database
+```
+
+## MCP Client 範例
+
+Claude Desktop：
+
+```json
+{
+  "mcpServers": {
+    "easy-pg-mcp": {
+      "command": "npx",
+      "args": ["-y", "easy-pg-mcp"],
+      "env": {
+        "PG_HOST": "localhost",
+        "PG_PORT": "5432",
+        "PG_USER": "YOUR USERNAME",
+        "PG_PASSWORD": "YOUR PASSWORD",
+        "PG_DATABASE": "YOUR DB NAME"
+      }
+    }
+  }
+}
+```
+
+Codex `config.toml`：
+
+```toml
+[mcp_servers.easy-pg-mcp]
+args = ["-y", "easy-pg-mcp"]
+command = "npx"
+enabled = true
+
+[mcp_servers.easy-pg-mcp.env]
+PG_HOST = "localhost"
+PG_PORT = "5432"
+PG_USER = "YOUR USERNAME"
+PG_PASSWORD = "YOUR PASSWORD"
+PG_DATABASE = "YOUR DB NAME"
+```
+
+## 可用工具
+
+| 工具 | 說明 |
+| --- | --- |
+| `pg_query` | 執行唯讀 SQL，例如 `SELECT` |
+| `pg_execute` | 執行資料修改 SQL，例如 `INSERT`、`UPDATE`、`DELETE` |
+| `pg_batch_execute` | 使用多組參數重複執行同一個資料修改 SQL |
+| `pg_import_csv` | 依 CSV header 將 UTF-8 CSV 匯入資料表 |
+| `pg_export_csv` | 將資料表匯出成 UTF-8 CSV |
+| `explain_query` | 對 `SELECT` 執行 `EXPLAIN` |
+| `list_tables` | 列出目前 schema 的 base tables |
+| `list_views` | 列出目前 schema 的 views |
+| `describe_table` | 顯示一個或多個資料表的欄位資訊 |
+| `describe_index` | 顯示資料表 indexes |
+| `list_triggers` | 列出目前 schema 的 triggers |
+| `get_current_privileges` | 顯示目前 PostgreSQL 使用者與 table grants |
+| `pg_run_approved_command` | 執行已核准的 pending command，僅在 `PG_POLICY_HOOK` 設定時註冊 |
+| `pg_list_pending_approvals` | 列出 pending approvals，僅在 `PG_POLICY_HOOK` 設定時註冊 |
+| `pg_cancel_approval` | 取消 pending approval，僅在 `PG_POLICY_HOOK` 設定時註冊 |
+
+當 `PG_READ_ONLY=true` 或 `PG_MCP_MODE=readonly` 時，`pg_execute`、`pg_batch_execute`、`pg_import_csv` 不會被註冊。
+
+## 參數語法
+
+node-postgres 使用 `$1`、`$2`、`$3` 這種 positional placeholders。不要使用 MySQL 的 `?` placeholder。
+
+`pg_execute` 範例：
+
+```json
+{
+  "sql": "UPDATE users SET email = $1 WHERE id = $2",
+  "params": ["new@example.com", 123]
+}
+```
+
+`pg_batch_execute` 範例：
+
+```json
+{
+  "sql": "INSERT INTO users (name, email) VALUES ($1, $2)",
+  "paramsList": [
+    ["Alice", "alice@example.com"],
+    ["Bob", "bob@example.com"]
+  ],
+  "transaction": "all"
+}
+```
+
+## 批次執行
+
+`pg_batch_execute` 會用多組參數重複執行同一個參數化寫入 SQL。`transaction` 可控制交易範圍：
+
+| 值 | 行為 |
+| --- | --- |
+| `all` | 預設值。所有資料列包在同一個 transaction |
+| `batch` | 每個內部分批各自使用一個 transaction |
+| `each` | 每組參數各自使用一個 transaction |
+| `none` | 不主動開啟 transaction |
+
+每筆執行結果會寫入 `PG_LOG_PATH` 下帶時間戳的 `.log` 檔，預設路徑為 `logs/`。Server 啟動時也會自動清除七天前的舊 log。
+
+## SQL Policy
+
+- `pg_query` 只允許單一 statement 的 `SELECT`、`SHOW`、`EXPLAIN`。
+- `explain_query` 只接受單一 `SELECT`，並在前方加上 `EXPLAIN` 執行。
+- `pg_execute` 在 write mode 下只允許單一 statement 的 `INSERT`、`UPDATE`、`DELETE`。
+- `pg_batch_execute` 與 `pg_import_csv` 使用和 `pg_execute` 相同的寫入規則。
+- `pg_export_csv` 會先檢查 table policy。
+- 禁止 multi-statement SQL。
+- `SELECT ... INTO` 與 locking reads 會被唯讀查詢工具拒絕。
+- `PG_MCP_DENY_TABLES` 優先於 `PG_MCP_ALLOW_TABLES`。
+- 若設定 `PG_MCP_ALLOW_TABLES`，所有偵測到的 table 都必須在 allowlist 內。
+
+Table policy 是根據 SQL parser 的 best-effort 檢查；PostgreSQL grants 仍然是最後的安全邊界。
+
+## Policy Hook 與 Approval
+
+設定 `PG_POLICY_HOOK` 後，server 會在內建 policy 檢查通過、但命令實際執行前，將每次工具操作 POST 到外部 hook。Hook 必須回傳以下其中一種結果：
+
+```json
+{ "status": "accept" }
+```
+
+```json
+{ "status": "reject", "message": "Writes are blocked outside maintenance windows." }
+```
+
+```json
+{ "status": "approval_required", "message": "User approval is required before updating users." }
+```
+
+若回傳 `approval_required`，server 會把待執行命令暫存在記憶體中，並回傳 `approvalId`。之後 MCP host 可以透過 `pg_run_approved_command` 搭配該 `approvalId` 執行命令。Pending approvals 只能使用一次，並會在 `PG_APPROVAL_TTL_SECONDS` 到期後失效。
+
+## 開發與測試
+
+```bash
+npm run build
+npm run test
+```
+
+若要執行 PostgreSQL integration tests，建立 `.env`：
+
+```env
+TEST_HOST=localhost
+TEST_PORT=5432
+TEST_USERNAME=test_user
+TEST_PASSWORD=test_password
+TEST_DB=test_database
+```
+
+測試會在 `TEST_DB` 建立並刪除暫時資料表、view、function、trigger。若缺少 `TEST_*` 變數，integration tests 會自動 skip。
+
+## 授權
+
+MIT。請見 [LICENSE.md](LICENSE.md)。

package/build/approvalStore.js

@@ -0,0 +1,58 @@
+import { randomUUID } from 'node:crypto';
+import { config } from './config.js';
+const pendingApprovals = new Map();
+export function createPendingApproval(input) {
+    cleanupExpiredApprovals();
+    const approvalId = `apv_${randomUUID()}`;
+    const createdAtMs = Date.now();
+    const expiresAtMs = createdAtMs + config.approvalTtlSeconds * 1000;
+    const pendingApproval = {
+        ...input,
+        approvalId,
+        createdAtMs,
+        expiresAtMs,
+    };
+    pendingApprovals.set(approvalId, pendingApproval);
+    return toSummary(pendingApproval);
+}
+export async function runApprovedCommand(approvalId) {
+    cleanupExpiredApprovals();
+    const pendingApproval = pendingApprovals.get(approvalId);
+    if (!pendingApproval) {
+        throw new Error(`Approval not found or expired: ${approvalId}`);
+    }
+    pendingApprovals.delete(approvalId);
+    return pendingApproval.command();
+}
+export function listPendingApprovals() {
+    cleanupExpiredApprovals();
+    return [...pendingApprovals.values()].map(toSummary);
+}
+export function cancelApproval(approvalId) {
+    cleanupExpiredApprovals();
+    const pendingApproval = pendingApprovals.get(approvalId);
+    if (!pendingApproval) {
+        throw new Error(`Approval not found or expired: ${approvalId}`);
+    }
+    pendingApprovals.delete(approvalId);
+    return toSummary(pendingApproval);
+}
+export function cleanupExpiredApprovals(now = Date.now()) {
+    for (const [approvalId, pendingApproval] of pendingApprovals.entries()) {
+        if (pendingApproval.expiresAtMs <= now) {
+            pendingApprovals.delete(approvalId);
+        }
+    }
+}
+function toSummary(pendingApproval) {
+    return {
+        approvalId: pendingApproval.approvalId,
+        functionName: pendingApproval.functionName,
+        statementType: pendingApproval.statementType,
+        tableNames: pendingApproval.tableNames,
+        message: pendingApproval.message ?? 'Approval required before executing this command.',
+        createdAt: new Date(pendingApproval.createdAtMs).toISOString(),
+        expiresAt: new Date(pendingApproval.expiresAtMs).toISOString(),
+        summary: pendingApproval.summary,
+    };
+}

package/build/config.js

@@ -0,0 +1,46 @@
+const DEFAULT_BATCH_MAX_SIZE = 100;
+const DEFAULT_APPROVAL_TTL_SECONDS = 300;
+const DEFAULT_LOG_PATH = 'logs';
+function parseBoolean(value) {
+    return value?.toLowerCase() === 'true';
+}
+function parsePositiveInt(value, defaultValue) {
+    const parsed = value ? Number.parseInt(value, 10) : NaN;
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : defaultValue;
+}
+function parseList(value) {
+    if (!value) {
+        return [];
+    }
+    return value
+        .split(',')
+        .map((item) => item.trim())
+        .filter(Boolean)
+        .map((item) => normalizeTableName(item));
+}
+export function normalizeTableName(table) {
+    return table.replace(/"/g, '').toLowerCase();
+}
+function resolveMode() {
+    const explicitMode = process.env.PG_MCP_MODE?.toLowerCase();
+    const readOnly = parseBoolean(process.env.PG_READ_ONLY);
+    if (readOnly || explicitMode === 'readonly' || explicitMode === 'read-only') {
+        return 'readonly';
+    }
+    return 'readwrite';
+}
+export const config = {
+    mode: resolveMode(),
+    allowTables: parseList(process.env.PG_MCP_ALLOW_TABLES),
+    denyTables: parseList(process.env.PG_MCP_DENY_TABLES),
+    batchMaxSize: parsePositiveInt(process.env.PG_BATCH_MAX_SIZE, DEFAULT_BATCH_MAX_SIZE),
+    logPath: process.env.PG_LOG_PATH?.trim() || DEFAULT_LOG_PATH,
+    policyHookUrl: process.env.PG_POLICY_HOOK?.trim() || undefined,
+    approvalTtlSeconds: parsePositiveInt(process.env.PG_APPROVAL_TTL_SECONDS, DEFAULT_APPROVAL_TTL_SECONDS),
+};
+export function isReadOnlyMode() {
+    return config.mode === 'readonly';
+}
+export function isPolicyHookEnabled() {
+    return Boolean(config.policyHookUrl);
+}

package/build/csv.js

@@ -0,0 +1,109 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+export async function readCsvFile(filePath) {
+    const content = await readFile(filePath, 'utf8');
+    const records = parseCsv(content);
+    if (records.length === 0) {
+        throw new Error('CSV import failed: file is empty.');
+    }
+    const headers = records[0].map((header) => header.trim());
+    if (headers.length === 0 || headers.some((header) => !header)) {
+        throw new Error('CSV import failed: header row contains an empty column name.');
+    }
+    const uniqueHeaders = new Set(headers.map((header) => header.toLowerCase()));
+    if (uniqueHeaders.size !== headers.length) {
+        throw new Error('CSV import failed: header row contains duplicate column names.');
+    }
+    const rows = records.slice(1).filter((row) => row.some((value) => value !== ''));
+    for (const [index, row] of rows.entries()) {
+        if (row.length !== headers.length) {
+            throw new Error(`CSV import failed: row ${index + 2} has ${row.length} columns, expected ${headers.length}.`);
+        }
+    }
+    return { headers, rows };
+}
+export async function writeCsvFile(filePath, headers, rows) {
+    const directory = path.dirname(filePath);
+    if (directory && directory !== '.') {
+        await mkdir(directory, { recursive: true });
+    }
+    const lines = [
+        serializeCsvRow(headers),
+        ...rows.map((row) => serializeCsvRow(headers.map((header) => stringifyCsvValue(row[header])))),
+    ];
+    await writeFile(filePath, `${lines.join('\n')}\n`, 'utf8');
+}
+function parseCsv(content) {
+    const rows = [];
+    let row = [];
+    let field = '';
+    let inQuotes = false;
+    for (let index = 0; index < content.length; index += 1) {
+        const char = content[index];
+        const nextChar = content[index + 1];
+        if (inQuotes) {
+            if (char === '"' && nextChar === '"') {
+                field += '"';
+                index += 1;
+            }
+            else if (char === '"') {
+                inQuotes = false;
+            }
+            else {
+                field += char;
+            }
+            continue;
+        }
+        if (char === '"') {
+            inQuotes = true;
+        }
+        else if (char === ',') {
+            row.push(field);
+            field = '';
+        }
+        else if (char === '\n') {
+            row.push(field);
+            rows.push(row);
+            row = [];
+            field = '';
+        }
+        else if (char === '\r') {
+            if (nextChar === '\n') {
+                continue;
+            }
+            row.push(field);
+            rows.push(row);
+            row = [];
+            field = '';
+        }
+        else {
+            field += char;
+        }
+    }
+    if (inQuotes) {
+        throw new Error('CSV parse failed: unterminated quoted field.');
+    }
+    if (field !== '' || row.length > 0) {
+        row.push(field);
+        rows.push(row);
+    }
+    return rows;
+}
+function serializeCsvRow(values) {
+    return values.map(escapeCsvValue).join(',');
+}
+function stringifyCsvValue(value) {
+    if (value === null || value === undefined) {
+        return '';
+    }
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    return String(value);
+}
+function escapeCsvValue(value) {
+    if (!/[",\r\n]/.test(value)) {
+        return value;
+    }
+    return `"${value.replace(/"/g, '""')}"`;
+}