dsh-sql 0.5.4 → 0.5.6

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 [返回简介](README.md) · [使用说明](docs/USAGE.md) · [验证记录](docs/VALIDATION.md)
 
+## 0.5.6 (2026-10-29)
+
+- 同步仓库与 npm 的简明介绍、中英文 README 和反馈入口；本次为文档与包元数据更新。
+- Sync npm descriptions and both README guides with the repository, including issue and pull-request links.
+
+## 0.5.5 (2026-10-28)
+
+- 写入确认与健康检查正确读取会话审批策略。never 或未知策略明确说明操作未执行及恢复方式；保留宿主拒绝、只读限制与完整 SQL 审批摘要。
+
 ## 0.5.4 (2026-10-28)
 
 - 修复 PostgreSQL 查询能修改会话默认设置，再通过写函数绕过只读保护的问题。每次查询强制使用独立只读事务并回滚；允许审批写入时查询工具仍保持只读。

package/README.en.md

@@ -4,7 +4,7 @@
 
 ![dsh-sql whale girl plugin cover](https://raw.githubusercontent.com/STARDUSTLC666/dsh-sql/master/assets/cover-whale-girl.png)
 
-Connect SQLite, MySQL or PostgreSQL to query data and inspect schemas.
+Connect SQLite, MySQL or PostgreSQL to query data and inspect schemas and statistics from DSH. Includes read-only protection, result and timeout limits, configurable write confirmation and separate connection and permission checks.
 
 [![npm](https://img.shields.io/npm/v/dsh-sql)](https://www.npmjs.com/package/dsh-sql) [![downloads](https://raw.githubusercontent.com/STARDUSTLC666/dsh-suite/npm-downloads/assets/dsh-sql-downloads.svg)](https://www.npmjs.com/package/dsh-sql)
 

package/README.md

@@ -4,7 +4,7 @@
 
 ![dsh-sql 鲸鱼娘插件封面](https://raw.githubusercontent.com/STARDUSTLC666/dsh-sql/master/assets/cover-whale-girl.png)
 
-连接 SQLite、MySQL 或 PostgreSQL，查询数据并检查数据库结构。
+连接 SQLite、MySQL 或 PostgreSQL，在 DSH 中查询数据、查看表结构与统计。提供只读保护、结果与超时限制、可配置的写操作确认，并分别报告连接和权限状态。
 
 [![npm](https://img.shields.io/npm/v/dsh-sql)](https://www.npmjs.com/package/dsh-sql) [![downloads](https://raw.githubusercontent.com/STARDUSTLC666/dsh-suite/npm-downloads/assets/dsh-sql-downloads.svg)](https://www.npmjs.com/package/dsh-sql)
 

package/docs/USAGE.en.md

@@ -1,5 +1,9 @@
 # dsh-sql usage guide
 
+## Confirmation in Full Access
+
+The plugin keeps its confirmation requirement. With approval policy `never`, it reports that confirmation is unavailable and performs no write. Switch to a mode that can ask, or explicitly set `writeApproval: false` yourself. Host denials still apply.
+
 [Overview](../README.en.md) · [Changelog](../CHANGELOG.md) · [Validation](VALIDATION.md)
 
 ## Current improvements

package/docs/USAGE.md

@@ -1,5 +1,9 @@
 # dsh-sql 使用说明
 
+## 完全权限下的确认
+
+插件保留单独确认要求。会话审批策略为 `never` 时不能弹框，会明确说明操作未执行；请切到可询问模式，或由用户明确设置 `writeApproval: false`。其它宿主拒绝仍生效，不自动放宽权限。
+
 [返回简介](../README.md) · [更新记录](../CHANGELOG.md) · [验证记录](VALIDATION.md)
 
 ## 本次改进

package/docs/VALIDATION.md

@@ -1,5 +1,9 @@
 # dsh-sql 验证记录
 
+## 2026-10-28：0.5.5
+
+[本次修复与验收边界](validation-0.5.5.md)。
+
 本页整理原 README 的历史验证说明，保留当时的版本、日期与范围。自动测试、启动检查、浏览器操作和真实服务验收分别记录，不能相互替代。更详细的版本验收文件仍保留在仓库中。
 
 ## 0.5.4（2026-10-28）

package/docs/validation-0.5.5.md

@@ -0,0 +1,7 @@
+# 0.5.5 验证记录（2026-10-28）
+
+Windows 74 项回归：73 通过、1 项真实 PostgreSQL 因本轮未配置服务而跳过。数据库适配器和只读事务代码本轮未改动；不以此冒充本轮真实 MySQL/PostgreSQL 验收。
+
+官方 DSH 0.2.1-rc.4 的真实 agent 回合调用 sql_exec：策略 never 返回插件的明确原因，未请求无效确认，也没有声称用户点了拒绝。原生 SQLite 查询通过；sql_health 将连接正常与写确认可用分开，never 时整体检查不误报正常。
+
+回归覆盖可询问策略、未知服务、保留宿主拒绝、只读配置、显式关闭审批和完整 SQL 摘要。未自动放宽任何写入保护；Electron 原生窗口未验收。

package/lib/approval.d.ts

@@ -0,0 +1,13 @@
+/** Read the effective Host policy without importing a second copy of its services. */
+export type ApprovalPolicy = 'ask' | 'never' | 'unknown';
+export interface ApprovalContext {
+    get?(name: string): unknown;
+    approval?: {
+        config?: {
+            policy?: unknown;
+        };
+        overrideOf?(session: unknown): unknown;
+    };
+}
+export declare function approvalPolicy(ctx: ApprovalContext, execution: unknown): ApprovalPolicy;
+export declare function approvalProblem(policy: ApprovalPolicy, setting: string): string | undefined;

package/lib/approval.js

@@ -0,0 +1,18 @@
+export function approvalPolicy(ctx, execution) {
+    try {
+        const service = (ctx.get ? ctx.get('approval') : ctx.approval);
+        const session = execution?.agent?.session;
+        const policy = (session === undefined ? undefined : service?.overrideOf?.(session)) ?? service?.config?.policy;
+        return policy === 'ask' || policy === 'never' ? policy : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+export function approvalProblem(policy, setting) {
+    if (policy === 'ask')
+        return undefined;
+    if (policy === 'never')
+        return '插件要求确认，但当前会话审批策略 never 不允许询问，操作未执行。请切换到可询问模式，或由用户明确设置 ' + setting + '=false / Confirmation is required but this session cannot ask; no action was performed.';
+    return '无法读取宿主审批策略，操作未执行。请检查 DSH 审批服务或插件配置 / Host approval policy unavailable; no action was performed.';
+}

package/lib/index.d.ts

@@ -10,6 +10,7 @@
  */
 import { type SqlConfig } from './config.js';
 import { type SqlToolDefinition } from './tools.js';
+import { type ApprovalContext } from './approval.js';
 /** cordis 服务注入：apply 里要用 ctx.tools，必须显式声明。 */
 export declare const name = "sql";
 export declare const inject: string[];
@@ -31,7 +32,7 @@ interface SqlToolExecution {
 /** Harness `tools/pre-execute` waterfall 监听器。 */
 type SqlPreExecuteListener = (exec: SqlToolExecution, next: () => Promise<SqlPreToolDecision>) => Promise<SqlPreToolDecision>;
 /** 插件所需的最小 ctx 面。 */
-export interface SqlPluginContext {
+export interface SqlPluginContext extends ApprovalContext {
     tools: {
         register(definition: SqlToolDefinition): () => void;
     };

package/lib/index.js

@@ -11,6 +11,7 @@ import { registerUpdates } from '@stardustlc/dsh-updates';
  */
 import { resolveConfig } from './config.js';
 import { buildSqlTools, summarizeWriteScript } from './tools.js';
+import { approvalPolicy, approvalProblem } from './approval.js';
 /** cordis 服务注入：apply 里要用 ctx.tools，必须显式声明。 */
 export const name = 'sql';
 export const inject = ['tools'];
@@ -20,11 +21,20 @@ export const inject = ['tools'];
 export function apply(ctx, config) {
     registerUpdates(ctx, { name: "dsh-sql" });
     const cfg = resolveConfig(config);
-    const { tools, adapters } = buildSqlTools(cfg);
+    const policyOf = (exec) => approvalPolicy(ctx, exec);
+    const { tools, adapters } = buildSqlTools(cfg, policyOf);
     if (cfg.writeApproval) {
         ctx.on('tools/pre-execute', async (exec, next) => {
             if (exec.name !== 'sql_exec')
                 return next();
+            const downstream = await next();
+            if (downstream.kind === 'deny')
+                return downstream;
+            if (cfg.readOnly)
+                return { kind: 'deny', reason: '当前连接为只读配置，sql_exec 已禁用 / Read-only configuration; sql_exec is disabled.' };
+            const problem = approvalProblem(policyOf(exec), 'writeApproval');
+            if (problem)
+                return { kind: 'deny', reason: problem };
             const args = (typeof exec.arguments === 'object' && exec.arguments !== null ? exec.arguments : {});
             const sql = typeof args.sql === 'string' ? args.sql : '';
             return {

package/lib/tools.d.ts

@@ -52,7 +52,7 @@ export interface SqlExecGateContext {
     signal?: unknown;
 }
 /** 构建六个工具定义；adapters 惰性创建并按连接名缓存。 */
-export declare function buildSqlTools(config: ResolvedSqlConfig): {
+export declare function buildSqlTools(config: ResolvedSqlConfig, policyOf?: (execution: unknown) => 'ask' | 'never' | 'unknown'): {
     tools: SqlToolDefinition[];
     adapters: Map<string, DatabaseAdapter>;
 };

package/lib/tools.js

@@ -402,7 +402,7 @@ const healthSchema = {
     additionalProperties: true,
 };
 /** 构建六个工具定义；adapters 惰性创建并按连接名缓存。 */
-export function buildSqlTools(config) {
+export function buildSqlTools(config, policyOf = () => 'unknown') {
     const cfg = config;
     const adapters = new Map();
     /** 只解析连接配置（不建连接），用于在打开数据库前挑选词法规则。 */
@@ -669,13 +669,13 @@ export function buildSqlTools(config) {
                 const rec = asRecord(value);
                 const connections = Array.isArray(rec.connections) ? rec.connections : [];
                 const bad = connections.filter((c) => asRecord(c).ok !== true);
-                const lines = ['dsh-sql 自检' + (bad.length === 0 ? '：全部连接正常。' : '：' + bad.length + ' 个连接异常。')];
+                const lines = ['dsh-sql 自检' + (rec.ok === true ? '：正常。' : '：发现问题。')];
                 for (const item of connections) {
                     const c = asRecord(item);
                     lines.push('- ' + c.name + '（' + c.engine + '）' + (c.ok === true ? ' ✅' : ' ❌ ' + String(c.error ?? '')));
                 }
                 lines.push('- 只读模式：' + (rec.readOnly === true ? '开（sql_exec 已禁用）' : '关'));
-                lines.push('- 写审批门：' + (rec.writeApproval === true ? '开' : '关'));
+                lines.push('- 写审批门：' + String(rec.writeApprovalDetail ?? (rec.writeApproval === true ? '开' : '关')));
                 lines.push('- 行数上限：' + String(rec.maxRows) + '；查询超时 ' + String(rec.queryTimeoutMs) + 'ms；写超时 ' + String(rec.execTimeoutMs) + 'ms');
                 return [{ type: 'text', text: lines.join('\n') }];
             },
@@ -683,12 +683,18 @@ export function buildSqlTools(config) {
         async execute(_rawArgs, exec) {
             const connections = await pingAllConnections(executionSignal(exec));
             const bad = connections.filter((c) => c.ok !== true);
+            const policy = policyOf(exec);
+            const writeApprovalReady = cfg.readOnly || !cfg.writeApproval || policy === 'ask';
+            const writeApprovalDetail = cfg.readOnly ? '只读配置，不允许写入' : !cfg.writeApproval ? '关闭；其它宿主策略仍生效' : policy === 'ask' ? '开启；经宿主询问' : policy === 'never' ? '当前策略 never 无法询问；请切换模式或由用户明确设置 writeApproval=false' : '无法读取宿主审批策略';
             return {
-                ok: bad.length === 0,
+                ok: bad.length === 0 && writeApprovalReady,
                 plugin: 'dsh-sql',
                 connections,
                 readOnly: cfg.readOnly,
                 writeApproval: cfg.writeApproval,
+                approvalPolicy: policy,
+                writeApprovalReady,
+                writeApprovalDetail,
                 maxRows: cfg.maxRows,
                 queryTimeoutMs: cfg.queryTimeoutMs,
                 execTimeoutMs: cfg.execTimeoutMs,

package/lib/update-client.js

@@ -437,7 +437,7 @@ function __stardustUpdatesClient(ctx, React, require, shared) {
 }
 
 /* STARDUSTLC_UPDATE_CLIENT_BODY_START */
-window.__ModuleLoader__.load(__stardustUpdatesWrap({id:"dsh-sql",factory:require=>({apply(){}})},{"name":"dsh-sql","version":"0.1.0","hasWorkbench":false,"packageVersion":"0.5.4","label":"数据库","labelEn":"SQL","suiteComponent":true}));
+window.__ModuleLoader__.load(__stardustUpdatesWrap({id:"dsh-sql",factory:require=>({apply(){}})},{"name":"dsh-sql","version":"0.1.0","hasWorkbench":false,"packageVersion":"0.5.6","label":"数据库","labelEn":"SQL","suiteComponent":true}));
 
 /* STARDUSTLC_UPDATE_CLIENT_BODY_END */
 })();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-sql",
-  "version": "0.5.4",
-  "description": "连接 SQLite、MySQL 或 PostgreSQL，查询数据并检查数据库结构。",
+  "version": "0.5.6",
+  "description": "DSH 数据库工具：SQLite / MySQL / PostgreSQL 查询、结构与统计、只读保护和写操作确认。欢迎提交 issues 和 PR。",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",