dsh-lh-data 0.1.0

package/lib/datasource/driver.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 数据库驱动的运行时加载。
+ *
+ * `mysql2` / `pg` 已随插件默认安装（`dependencies`），但仍走**动态 import**：
+ * 用到哪个才加载哪个，CLI 剖面与只用文件导入的用户不会被这两个包拖慢启动。
+ * 万一运行环境里缺包（裁剪安装、pnpm 过滤等），抛 `DataSourceError('DRIVER_MISSING')`
+ * 并在消息里带上安装命令，而不是崩在裸栈上。
+ *
+ * 导入说明符必须走变量，不能用字面量——字面量会让 TypeScript 与打包器在解析期
+ * 就去解析这两个包，缺包时 typecheck / build 直接失败。
+ */
+import type { DataSourceType } from './types';
+export declare const DRIVER_INSTALL_HINTS: Readonly<Record<DataSourceType, string>>;
+interface MysqlLike {
+    createPool(options: Record<string, unknown>): MysqlPoolLike;
+    createConnection(options: Record<string, unknown>): Promise<MysqlConnLike>;
+}
+export interface MysqlPoolLike {
+    execute(sql: string, params?: unknown[]): Promise<[unknown[], unknown]>;
+    end(): Promise<void>;
+}
+interface MysqlConnLike {
+    execute(sql: string, params?: unknown[]): Promise<[unknown[], unknown]>;
+    end(): Promise<void>;
+}
+interface PgLike {
+    Pool: new (options: Record<string, unknown>) => PgPoolLike;
+}
+export interface PgPoolLike {
+    query(sql: string, params?: unknown[]): Promise<{
+        rows: unknown[];
+    }>;
+    end(): Promise<void>;
+}
+/** 仅供测试：清掉模块级缓存。 */
+export declare function resetDriverCache(): void;
+export declare function loadMysqlDriver(): Promise<MysqlLike>;
+export declare function loadPgDriver(): Promise<PgLike>;
+export {};

package/lib/datasource/errors.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 数据源模块的统一错误类型。
+ *
+ * 主机侧的边界（工具 / 管理接口）把它翻译成 `ToolError` / `AdminServiceError`。
+ * 错误文本一律脱敏：不含密码、不含本地物理表名。
+ */
+export type DataSourceErrorCode = 'NOT_FOUND' | 'DRIVER_MISSING' | 'UNREACHABLE' | 'BAD_REQUEST' | 'TOO_MANY_ROWS' | 'IMPORT_FAILED';
+export declare class DataSourceError extends Error {
+    readonly code: DataSourceErrorCode;
+    constructor(code: DataSourceErrorCode, message: string);
+}
+export declare function isDataSourceError(error: unknown): error is DataSourceError;
+/**
+ * 原生驱动错误 → 脱敏的中文提示。
+ * 只保留可定位的主机与端口，凭据绝不进文本。
+ */
+export declare function describeCause(error: unknown): string;
+/**
+ * 连接 / 查询异常归一为 `DataSourceError`。
+ * 已经是 `DataSourceError` 的（如 DRIVER_MISSING）保持原语义，其余按「连不上」处理，
+ * 这样工具与设置页永远不会把驱动的裸栈抛给模型 / 浏览器。
+ */
+export declare function wrapConnectionError(error: unknown, host: string, port: number): unknown;
+/** 错误码 → HTTP 状态码（管理接口用；工具侧另有一套映射）。 */
+export declare function dataSourceErrorStatus(code: DataSourceErrorCode): number;

package/lib/datasource/importer.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 远端表 → 本地数据集的导入。
+ *
+ * 落库完全复用文件导入的那一套（`createDatasetTable` / `insertRows` / `DatasetStore`），
+ * 因此导进来的数据集与 Excel 导入的**结构完全一致**，八个 `dataset_*` 工具零改动可用。
+ * 远端表名只出现在发往远端的 SQL 里，本地表名仍走 `generateTableName` 白名单。
+ */
+import type { ColumnInfo } from '../parse';
+import { type DataServices } from '../store';
+import { type ToolExec } from '../tooling';
+import type { DataSourceRecord } from './types';
+export declare const REMOTE_IMPORT_JOB_KIND = "datasource-import";
+export interface RemoteImportParams {
+    scopeKey: string;
+    source: DataSourceRecord;
+    tableName: string;
+    schemaName?: string | null;
+    /** 数据集登记名；缺省取远端表名。 */
+    name?: string | null;
+    /** 只导入前 N 行；配合 `datasourceMaxImportRows` 双重夹紧。 */
+    limit?: number | null;
+}
+export interface RemoteImportContext {
+    signal: AbortSignal;
+    /** 有 agent 才能回注后台任务的完成通知；设置页导入时传 undefined。 */
+    exec?: ToolExec;
+    background?: boolean;
+}
+export interface RemoteImportResult {
+    datasetId: string;
+    name: string;
+    rowCount: number;
+    columnCount: number;
+    columns: ColumnInfo[];
+    status: 'ready' | 'running';
+    jobId?: string;
+}
+export declare function importRemoteTable(services: DataServices, params: RemoteImportParams, context: RemoteImportContext): Promise<RemoteImportResult>;

package/lib/datasource/source-sql.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `lh_data_sources` 的 DDL 与行映射。
+ *
+ * 数据源是**全局**的（catalog 库，跨工作区共享），与 `dataset_scopes` 同库。
+ * DDL 与行映射单独放这里，`source-store.ts` 只留 CRUD，避免类膨胀。
+ */
+import type { Row } from '../db';
+import type { DataSourceRecord } from './types';
+export declare const SOURCE_SCHEMA_SQL = "\nCREATE TABLE IF NOT EXISTS lh_data_sources (\n  id TEXT PRIMARY KEY,\n  name TEXT NOT NULL,\n  type TEXT NOT NULL,\n  host TEXT NOT NULL,\n  port INTEGER NOT NULL,\n  database_name TEXT NOT NULL,\n  username TEXT NOT NULL,\n  password_enc TEXT NOT NULL,\n  ssl_mode TEXT,\n  pool_max INTEGER,\n  description TEXT,\n  status TEXT NOT NULL DEFAULT 'unknown',\n  last_error TEXT,\n  last_checked_at INTEGER,\n  created_at INTEGER NOT NULL,\n  updated_at INTEGER NOT NULL\n);\nCREATE UNIQUE INDEX IF NOT EXISTS idx_lh_data_sources_name ON lh_data_sources(name);\n";
+export declare function makeSourceId(): string;
+export declare function rowToSource(row: Row): DataSourceRecord;

package/lib/datasource/source-store.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 数据源的持久化：catalog 库 `lh_data_sources` 的 CRUD。
+ *
+ * 密码在这一层加密落库；改 / 删数据源会顺带关掉对应的连接池，避免缓存里残留
+ * 旧凭据。`list()` / `find()` 返回的是含密文的完整记录——**绝不能直接序列化
+ * 给前端或模型**，边界处必须过 `toView()` / 工具侧的脱敏。
+ */
+import { type DbConfig } from '../db';
+import type { DataSourceConfig, DataSourceInput, DataSourcePatch, DataSourceRecord } from './types';
+export declare class DataSourceStore {
+    private readonly cfg;
+    private initialized;
+    constructor(cfg: DataSourceConfig & DbConfig);
+    private db;
+    list(): Promise<DataSourceRecord[]>;
+    /** 按 id 或登记名查找；找不到返回 undefined（不抛错）。 */
+    find(reference: string): Promise<DataSourceRecord | undefined>;
+    require(reference: string): Promise<DataSourceRecord>;
+    /** 全局唯一的名字：已存在则追加 `_2` / `_3`。 */
+    uniqueName(name: string): Promise<string>;
+    create(input: DataSourceInput): Promise<DataSourceRecord>;
+    update(id: string, patch: DataSourcePatch): Promise<DataSourceRecord>;
+    /** 记录一次连通性检测的结果。 */
+    recordCheck(id: string, success: boolean, error: string | null): Promise<void>;
+    remove(id: string): Promise<void>;
+    private insert;
+}
+export declare function createSourceStore(cfg: DataSourceConfig & DbConfig): DataSourceStore;

package/lib/datasource/types.d.ts

@@ -0,0 +1,119 @@
+/**
+ * 数据源（DataSource）的类型定义。
+ *
+ * 数据源 = 一条远程关系型数据库的连接配置，全局登记在 catalog 库，跨工作区共享；
+ * 导入产出的数据集仍落在**当前工作区**的 scope 库里。
+ */
+import type { ColumnType } from '../parse';
+/** 支持的关系型数据库类型。 */
+export type DataSourceType = 'mysql' | 'postgresql';
+/** 连通状态：从未检测 / 最近一次成功 / 最近一次失败。 */
+export type DataSourceStatus = 'unknown' | 'connected' | 'error';
+/**
+ * 与 `DataConfig` 结构同源的最小视图。
+ * 只声明本模块真正读取的键，避免 `datasource/*` → `store.ts` 的循环依赖。
+ */
+export interface DataSourceConfig {
+    datasourceEnabled: boolean;
+    datasourceFetchBatchSize: number;
+    datasourceConnectTimeoutMs: number;
+    datasourceMaxImportRows: number;
+    datasourceEncryptKey: string;
+}
+/** catalog 库 `lh_data_sources` 的一行。`passwordEnc` 恒为密文。 */
+export interface DataSourceRecord {
+    id: string;
+    name: string;
+    type: DataSourceType;
+    host: string;
+    port: number;
+    database: string;
+    username: string;
+    passwordEnc: string;
+    sslMode: string | null;
+    poolMax: number | null;
+    description: string | null;
+    status: DataSourceStatus;
+    lastError: string | null;
+    lastCheckedAt: number | null;
+    createdAt: number;
+    updatedAt: number;
+}
+/** 新建一条数据源需要的字段（密码为明文，落库前加密）。 */
+export interface DataSourceInput {
+    name: string;
+    type: DataSourceType;
+    host: string;
+    port: number;
+    database: string;
+    username: string;
+    password: string;
+    sslMode?: string | null;
+    poolMax?: number | null;
+    description?: string | null;
+}
+/** 改一条数据源：字段缺省表示不改；`password` 给空串表示清空。 */
+export interface DataSourcePatch {
+    name?: string;
+    type?: DataSourceType;
+    host?: string;
+    port?: number;
+    database?: string;
+    username?: string;
+    password?: string | null;
+    sslMode?: string | null;
+    poolMax?: number | null;
+    description?: string | null;
+    status?: DataSourceStatus;
+    lastError?: string | null;
+    lastCheckedAt?: number | null;
+}
+/** 明文连接参数：只在内存里流转，绝不落库、绝不回显给前端或模型。 */
+export interface ConnectionConfig {
+    host: string;
+    port: number;
+    database: string;
+    username: string;
+    password: string;
+    sslMode: string | null;
+    poolMax: number | null;
+    connectTimeoutMs: number;
+}
+/** 连接器返回的列元数据（方言无关，已把远端类型映射成本项目的列类型）。 */
+export interface RemoteColumn {
+    name: string;
+    nativeType: ColumnType;
+    nullable: boolean;
+    comment: string | null;
+}
+export interface RemoteTable {
+    tableName: string;
+    schemaName: string | null;
+    /** 远端的估计行数（MySQL `TABLE_ROWS` / PG `reltuples`），可能为 -1（未知）。 */
+    rowCount: number;
+    primaryKey: string | null;
+    columns: RemoteColumn[];
+}
+export interface SchemaSummary {
+    schemaName: string;
+    tableCount: number;
+}
+export interface ConnectionTestResult {
+    success: boolean;
+    latency: number;
+    version: string | null;
+    error: string | null;
+}
+/** 分块拉取的区间。 */
+export interface FetchRange {
+    limit?: number;
+    offset?: number;
+}
+/** 导入一张远端表的请求（`datasource_import` 与设置页共用）。 */
+export interface ImportRequest {
+    scopeKey: string;
+    tableName: string;
+    schemaName?: string | null;
+    name?: string | null;
+    limit?: number | null;
+}

package/lib/db.d.ts

@@ -0,0 +1,91 @@
+/**
+ * libSQL 客户端与生命周期。
+ *
+ * 移植自 `agentic-data-mini` 的 `src/lib/primitives/db.ts`，保留其关键行为：
+ * URL 优先级、裸路径补 `file:`、启动 PRAGMA（WAL + 外键）、日志不打印 authToken。
+ * 插件侧新增：按 scope 解析库文件（`perWorkspace`）+ `closeAllDatabases()` 供
+ * `ctx.effect()` 在 HMR / 卸载时确定性释放（设计文档 §8）。
+ */
+import { type Client } from '@libsql/client';
+/** 无损 JSON 值（与 dsh 的 `snapshotJsonValue` 边界一致）。 */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** 一行查询结果：键为列名，值保证是无损 JSON。 */
+export type Row = {
+    [key: string]: JsonValue;
+};
+export interface RunResult {
+    changes: number;
+    lastInsertRowid: number;
+}
+export interface PreparedStatement {
+    all(...params: unknown[]): Promise<Row[]>;
+    get(...params: unknown[]): Promise<Row | undefined>;
+    run(...params: unknown[]): Promise<RunResult>;
+}
+/** 本模块需要的配置子集（由 `store.ts` 的 DataConfig 提供）。 */
+export interface DbConfig {
+    dbPath: string;
+    dbUrl: string;
+    authToken: string;
+    perWorkspace: boolean;
+}
+/** 近似 bun:sqlite 的兼容层：封装 @libsql/client。 */
+export declare class Database {
+    private readonly client;
+    readonly url: string;
+    readonly remote: boolean;
+    private initPromise;
+    constructor(client: Client, url: string, remote: boolean);
+    prepare(sql: string): PreparedStatement;
+    /** 执行多条语句（建表 / 建索引）。 */
+    exec(sql: string): Promise<void>;
+    close(): void;
+    private run;
+    /** PRAGMA 只做一次；远程库不支持时忽略。 */
+    private ensureInit;
+}
+/**
+ * 把 libSQL 的返回值规整成无损 JSON。
+ *
+ * libSQL 的行对象同时挂着具名列与**不可枚举**的数字索引 `0..n` 和 `length`
+ * （行既能按名也能按位置访问）。dsh 的 `snapshotJsonValue` 把「存在不可枚举的
+ * 自有属性」判为有损 —— 工具返回值会被直接拒为 `INVALID_TOOL_OUTPUT`
+ * （`value is not lossless JSON`）。这里统一重建为只含可枚举字符串键的纯对象；
+ * 顺带把 JSON 无法无损表达的值转成 JSON 安全形式：
+ * BigInt（超安全整数范围转字符串）、BLOB（base64）、NaN / ±Infinity（null）、
+ * `-0`（0）、Date（ISO 字符串）、function / symbol（null）。
+ */
+export declare function toJsonValue(value: unknown, depth?: number): JsonValue;
+/** 一行 → 只含可枚举字符串键的纯对象。 */
+export declare function toJsonRow(row: unknown): Row;
+/** 稳定短哈希：物理表名前缀与 perWorkspace 库文件后缀都用它。 */
+export declare function shortHash(input: string, length?: number): string;
+/** 仅用于兜底消毒的标识符（保留中文）：移植自参考实现的 `sanitizeId`。 */
+export declare function sanitizeId(name: string): string;
+/** 默认库目录：`$DSH_HOME/lh-data`。 */
+export declare function defaultDbDirectory(): string;
+/**
+ * 不含 scope 后缀的库 URL —— 连接优先级链的终点：
+ * `dbUrl` > `dbPath` > `SQLITE_PATH` > `TURSO_DATABASE_URL` > 默认本地文件。
+ */
+export declare function baseDbUrl(cfg: DbConfig): string;
+/**
+ * 连接优先级：`dbUrl` > `dbPath` > `SQLITE_PATH` > `TURSO_DATABASE_URL` > 默认本地文件。
+ * `perWorkspace` 且是本地库时，为每个 scope 派生独立库文件。
+ */
+export declare function resolveDbUrl(cfg: DbConfig, scopeKey: string): string;
+/**
+ * 目录库：**不做 scope 分片**的固定库，供工作区注册表使用。
+ *
+ * `perWorkspace=false` 时它与业务库是同一个 URL（同一个 `Database` 实例，
+ * 注册表与 datasets 表共存）；`perWorkspace=true` 时它是没有后缀的那份
+ * `data.db`，与各工作区的 `data-<hash>.db` 并列。
+ * 远程库（`libsql://`）不做分片，两种情况都是同一个库。
+ */
+export declare function resolveCatalogDatabase(cfg: DbConfig): Database;
+/** 惰性建立连接（不在 apply() 里同步建立），按 url 缓存单例。 */
+export declare function resolveDatabase(cfg: DbConfig, scopeKey: string): Database;
+/** 关闭全部连接：`ctx.effect()` 的 disposer 调用它。 */
+export declare function closeAllDatabases(): void;

package/lib/http-common.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 自建 HTTP 路由的公共层（视图路由与管理路由共用）。
+ *
+ * 抽出原因：`http.ts` 的视图路由已有 160 行，再加管理路由会失控；两路由共享
+ * 同样的「鉴权 + JSON 收发 + queryInt 解析」原语，单独成模块避免复制。
+ *
+ * 仅主机侧使用；`node:http` 的类型在这里统一引入，视图/管理路由都从这里取。
+ */
+import type { IncomingMessage } from 'node:http';
+/** 路由需要的请求面（duck-typed：只用这几个字段）。 */
+export interface RouteRequest {
+    method?: string;
+    url?: string;
+}
+export interface RouteResponse {
+    writeHead(status: number, headers?: Record<string, string>): unknown;
+    end(body?: string): unknown;
+}
+export declare const JSON_HEADERS: Record<string, string>;
+export declare function sendJson(response: RouteResponse, status: number, payload: unknown): void;
+export declare function sendError(response: RouteResponse, status: number, code: string, message: string): void;
+export declare function queryInt(raw: string | null): number | undefined;
+/**
+ * 鉴权：复用平台同样的连接围栏（Host/Origin + 浏览器登录态）。
+ * 通过返回 undefined；否则返回应写入的 HTTP 状态码（401 / 403）。
+ */
+export declare function authorize(connection: {
+    requestRejection(request: unknown): 401 | 403 | undefined;
+}, request: unknown): 401 | 403 | undefined;
+/** 读取并 JSON 解析请求体，超 `maxBytes` 或非法 JSON 时抛错（由调用方映射成响应）。 */
+export declare function readJsonBody(request: IncomingMessage & RouteRequest, maxBytes: number): Promise<unknown>;

package/lib/http.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 前端分页取数的 HTTP 路由 —— 设计文档 §5.5 / §9。
+ *
+ * 只暴露两个能力：按 `viewId` 取一页、按 `viewId` 释放视图。
+ * 接口**不接受任何 SQL**：语句由 `ViewRegistry` 在主机侧持有，因此没有注入面。
+ * 每个请求先过 `connection.requestRejection()`（Host/Origin 围栏 + 浏览器鉴权）。
+ */
+import type { DataServices } from './store';
+/**
+ * 注册视图路由。返回 disposer；宿主缺失（`webServer` / `connection` 任一不可用）时返回 undefined。
+ * 路由路径重复会抛错（webserver 的契约），由调用方决定如何降级。
+ */
+export declare function registerViewRoutes(services: DataServices): (() => void) | undefined;

package/lib/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 插件入口：`name` / `inject` / `Config` / `apply`。
+ *
+ * 装载链路与 `dsh-lh-judge` 完全一致：
+ * `pnpm run build` → `pnpm dsh plugin --profile web add D:\fastwork\projects\node\dsh-lh-data`
+ *
+ * 职责（设计文档 §7.2 / §9）：
+ * - 注册八个 `dataset_*` 工具（句柄化，物理表名不外泄）；
+ * - `tools/pre-execute` 给写工具加 `ask` 门禁（无审批通道即拒绝，fail-closed）；
+ * - `ctx.tools.guard()` 单调兜底：写工具缺少归属句柄一律拒绝；
+ * - `ctx.systemPrompt.section()` 注入使用引导（可选依赖）；
+ * - `ctx.effect()` 在 HMR / 卸载时关闭 libSQL 连接。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import Schema from '@deepseek-ai/schemastery';
+import { type DataConfig } from './store';
+import { type ToolRegistry } from './tooling';
+/** cordis 用于加载/去重的唯一标识。 */
+export declare const name: string;
+/** 等 `ctx.tools` 就绪后才 apply。 */
+export declare const inject: string[];
+/** 插件与 dsh 运行时交互的最小上下文（duck-typed：只声明实际用到的成员）。 */
+export interface PluginContext {
+    tools: ToolRegistry;
+    on(event: string, handler: (...args: any[]) => any): void;
+    effect?(setup: () => (() => void) | void): () => void;
+    inject?(deps: string[], callback: (injected: unknown) => void): unknown;
+    logger?: {
+        info?(message: string): void;
+        warn?(message: string): void;
+    };
+}
+/**
+ * 插件配置。类型与 `store.ts` 的 DataConfig 同源（在此只做具名导出），
+ * 避免 tools → index 的类型循环。
+ */
+export interface Config extends DataConfig {
+}
+export declare const Config: Schema<Config>;
+export declare function validateConfig(cfg?: Partial<DataConfig>): Config;
+export declare function apply(ctx: Context, config: Config): void;
+export { closeAllDatabases } from './db';
+export { buildColumns, fillSamples, mapRowKeys } from './datasource/columns';
+export { decryptPassword, encryptPassword, isValidEncryptedFormat, resolveEncryptKey } from './datasource/crypto';
+export { closeAllConnectors } from './datasource/connection';
+export { inferColumnType, isCodeOrIdField, isLargeNumber, parseCSV, parseXLSX, sanitizeColumnName, } from './parse';
+export { canonicalDirectory, isInside, normalizeDirectory, resolveInputFile } from './scope';
+export { SqlError, buildStructuredQuery, substituteDatasetAlias, validateReadOnlyQuery } from './sql';
+export { PHYSICAL_TABLE_PATTERN, assertPhysicalTableName, generateTableName } from './store';
+export { PLUGIN_NAME } from './tooling';