@chengxianglibra/dsh-data-analysis 0.1.1 → 0.2.0

package/README.md

@@ -1,72 +1,158 @@
 # @chengxianglibra/dsh-data-analysis
 
-由个人维护的 DeepSeek Harness 社区插件，并非 DeepSeek 官方发行或维护的软件包。
+在 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 中，用自然语言完成数据分析，
+浏览和复用业务指标定义，并将结果整理为可交互、可离线阅读的图表、报告和看板。
+语义分析能力由 [Marivo](https://github.com/chengxianglibra/marivo) 提供；本地文件也可直接使用 pandas 或 DuckDB。
 
-DeepSeek Harness 的 Marivo 集成插件。当前包提供：
+本项目是个人维护的社区插件，并非 DeepSeek 官方发行或维护的软件。
 
-- 精确 Marivo 0.5.3 共享 Runtime 与 zero-init per-Workspace binding；
-- `marivo_help` 实时公共 Help transport；
-- `marivo_datasource_test` 的 DSH Credentials 收集与显式 connection test；
-- `marivo_datasource_access` 的 30 分钟、最多 64 次 foreground Shell credential lease；
-- `marivo_evidence_sources({ session_id, sources })` 的可移植 Artifact-owned Finding 来源交付；
-- `emit_dataset(BaseFrame, ...)`、`emit_computed(DataFrame, ...)` 与
-  `emit_session_trace(SessionGraph, ...)` 的有界 JavaScript 投影；
-- 随包分发并挂载的 `dsh-data-analysis-report` Skill，以及 `marivo-analysis` 激活后的按需路由。
+## 安装
 
-旧 `marivo_test`、`marivo_report_render`、`ReportDocument`、报告 parser/renderer/publisher、专用报告 Web
-卡片与 replay 入口已删除，不提供 alias。
+### 环境准备
 
-## Compatibility
+- Node.js `^22.19.0 || >=24.0.0`，与 DeepSeek Harness 一致：22.x 需至少 22.19.0，或使用 24.0.0 及以上版本；不支持 23.x。
+- 已安装并配置好 DeepSeek Harness `>=0.1.5-rc.1`（rc.1 验收状态见验证指南；范围内未来版本不视为已验收）。
+- `pnpm` 可在命令行中使用，供 Harness 安装插件。
+- 已安装 Python 3.10+，命令行可运行 `python3`（Windows 为 `python`），且支持 `venv`/`ensurepip`；部分 Linux 发行版需额外安装 `python3-venv`。
 
-包内 `dshDataAnalysisCompatibility` 是唯一运行时兼容声明：
+默认安装方式会在首次启动时使用本机 Python 创建独立的虚拟环境，并通过 pip 安装 Marivo，无需预装 Marivo 或 uv。
+首次启动需要联网下载依赖，请等待环境准备完成。
 
-- DSH distribution 与所有必需 peer 精确使用 `0.1.1-rc.2`；
-- Marivo package spec 精确为 `marivo[duckdb,trino,clickhouse]==0.5.3`；
-- 项目自有 Runtime marker 为 `dsh-data-analysis-runtime/v2`；
-- 子进程策略为 `direct-argv-inherited-env-snapshot-overlay-v2`。
+### 安装并启动
 
-管理员解释器的 `marivo.__version__` 与 package identity 必须精确匹配；不使用 capability/version matrix。
+将插件安装到 Web Profile：
 
-## Tool contracts
+```bash
+dsh plugin --profile web add @chengxianglibra/dsh-data-analysis
+```
+
+安装后启动 Web Profile；如果已在运行，请先退出再重新启动：
 
-```text
-marivo_help({ targets: string[] })
-marivo_datasource_test({ name: string })
-marivo_datasource_access({ name: string })
-marivo_evidence_sources({
-  session_id: string,
-  sources: Array<{ artifact_ref: string, finding_id: string }>
-})
+```bash
+dsh --profile web
 ```
 
-`marivo_datasource_test` 只拥有缺失 Credentials 的 DSH/Web 闭环和显式连接测试；
-`marivo_datasource_access` 只签发有界 foreground Shell lease，不执行连接测试。`md.inspect(...)`、
-Session recovery、Artifact revalidation、Quality、Evidence 读取、Session Graph 与 `to_pandas()` 都直接使用
-Marivo 公共 API，不增加 convenience Tool。
+在 Web 界面选择分析使用的工作区（Workspace），新建会话并发送一条消息。
+会话标题旁按顺序显示“数据源”“语义层”“报告”三个入口，浏览页面在原生右侧标签页打开。本文以 Web 界面为例。
 
-## 报告交付
+### 本地文件分析
 
-仅当用户明确请求 HTML/Web 或耐久报告、接受生成提议，或修改已有 bundle 时，Agent 加载
-`dsh-data-analysis-report`；普通长回答或多图表/表格不会自动产出文件。已有分析恢复并 revalidate persisted
-Artifacts，不为报告展示重新执行 `observe`。
-该 Skill 只提供内容组织、布局、样式和检查原则，不包含页面 Starter、通用 chart helper、可视化 DSL 或
-HTML Checker。配套 assets 提供 `ReportData` 读取、精简 Artifact 摘要和 Session DAG；Python report-kit
-分别通过 `emit_dataset`、`emit_computed`、`emit_session_trace` 发射 Artifact、pandas DataFrame 与 Graph
-快照；Artifact 与 Graph emitter 默认 `reader`，明确审计请求才使用 `audit`。多 Session 的独立 Graph 集中展示，
-Frame preview 只按精确 Session 与 Artifact identity 关联。Agent 自由生成
-`<workspace>/<new-report-directory>/index.html` 与可选相对资源。Native/both 的
-最终入口使用顶层 DSH `write` / `edit`，并以精确 Markdown 行内路径交付，让 DSH Web 复用 Produced Files
-提供点击；Code-only 在 `run_code` 内使用同一 Tool，但嵌套 mutation 只保证精确路径。插件不创建报告对象、
-digest、不可变发布、历史字节 replay 或 share link。
+上传文件后直接提问，或指定 Workspace 中已有文件。助手可在插件绑定的 Python 环境中使用 pandas
+或原生 DuckDB 分析 CSV、JSON、Parquet，无需先配置数据源或建立语义模型；需要时可继续生成报告。
+默认安装包含 Marivo 的 `duckdb` extra（同时保留 `trino`、`clickhouse`）。Excel `.xlsx` 通过 DuckDB 的
+[excel 扩展](https://duckdb.org/docs/stable/core_extensions/excel.html)读取；首次使用需要联网下载扩展，
+并允许写入 DuckDB 扩展缓存。它不是额外的 Python 包，无需为此安装 `openpyxl`。
+旧版 `.xls` 不在该扩展支持范围内，需要先转换为 `.xlsx`、CSV 或 Parquet。
 
-## 验证
+纯文件分析无需经过 Marivo `md.raw_sql`。下面的数据源配置流程适用于数据库连接和需要复用的 Marivo 数据源。
 
-```bash
-npm run check
-npm run build
-npm run verify:plugin-package
+## 能力
+
+| 你想做什么 | 插件提供的能力 |
+| --- | --- |
+| 回答业务问题 | 用自然语言提出问题，分析指标趋势、比较不同时间或业务分组、探索变化原因 |
+| 分析本地文件 | 复用原生附件路径，以 pandas 或 DuckDB 直接计算，并按需交付图表或报告 |
+| 连接数据 | 配置数据源、管理连接凭证并测试连接；默认包含 DuckDB、Trino、ClickHouse 支持 |
+| 统一分析口径 | 与 Agent 一起整理和复用指标、维度等业务定义，浏览语义对象及其关系 |
+| 明确分析对象 | 在输入框通过 `@` 搜索并引用已有语义对象 |
+| 展示分析结果 | 生成包含文字、指标卡、图表、表格和来源说明的报告或看板 |
+| 阅读与分享 | 交互筛选、调整呈现、保存版本，并下载 HTML 离线阅读 |
+
+## 如何使用
+
+### 1. 准备数据源
+
+在会话标题旁打开“数据源”，查看所属工作区的连接属性与配置状态：
+
+1. 点击“新增数据源”，选择引擎，按表单填写名称及连接信息。
+2. 如果需要身份认证，在同一表单的“连接凭证”中直接填写用户名、密码或令牌。
+3. 测试连接，根据结果检查地址、凭证或访问权限。
+
+凭证引用名自动生成，可展开“凭证引用名 · 确认或修改”查看和调整；也可填写已有引用，并将值留空以复用凭证。
+编辑时已保存的凭证值不回显，留空沿用；填写新值默认使用新的引用，不删除旧的共享凭证。
+手动指定已存在的引用并填写新值时，不会自动覆盖，需到凭证页确认更新。
+已有数据源可点击“编辑配置”修改连接信息，名称和引擎保持不变；保存后重新测试。
+
+管理员可在 Harness 当前 profile 的本插件配置项下设置 `datasourceDefaults`，按引擎类型为新建表单填入默认值：
+
+```yaml
+datasourceDefaults:
+  trino:
+    host: trino.internal.example
+    port: 443
 ```
 
-当前架构与验收边界见仓库根目录的[总体架构](../../docs/architecture.md)、
-[插件能力优化设计](../../docs/plan/plugin-capability-optimization-design.md)和
-[v2 验收记录](../../docs/acceptance/plugin-capability-optimization-v2.md)。
+这是插件配置片段，随 Harness 现有配置加载机制生效；不是独立配置文件。未指定的字段保持原样，用户可修改或清空填充值；
+切换引擎时清空表单并应用目标引擎的默认值。编辑或复用已有数据源不应用这些默认值。
+只配置非敏感普通字段，不能设置 `*_env` 凭据引用或凭据值；内部地址只保存在部署环境的配置中，不必加入插件源码。
+打开新建表单时按当前 Runtime 校验引擎、字段和类型，错误会明确显示且不回显配置值；配置错误不阻止已有数据源编辑。
+
+分析需要新增或修复数据源时，助手可自动打开所属会话的右侧配置页。填写后点击“保存并测试，成功后继续”；
+缺少凭证时继续在凭证表单补齐，测试成功后原调用返回，助手再核验目标表并继续分析。
+请求页默认显示新增表单；切换“使用已有数据源”后，可选择已有连接并验证，无需重复创建。测试失败保留已保存的配置，允许修正后重试；取消请求不会作为成功继续。
+
+更新插件后，如果旧浏览器页面中工具正在等待、却没有打开配置 Tab，也没有“待配置”入口，
+先刷新浏览器页面以加载当前客户端。仍存活的原请求会重新显示；刷新页面不等于重启 Host。
+若原调用已取消或 Host 已重启，需要重新发起配置请求。
+请通过凭证表单提交密码或令牌，不要粘贴到聊天消息中。
+
+### 2. 用自然语言提出分析问题
+
+说明使用哪些数据、时间范围、指标口径和希望得到的结果。例如：
+
+> 使用订单数据，分析 2026 年 8 月的销售额和订单量，与 7 月比较，按渠道拆分，并说明数据来源和口径。
+
+> 检查最近七天的查询耗时，找出耗时最高的查询类型，给出趋势图和明细表。
+
+如果还没有整理业务定义，可以先让 Agent 帮助梳理：
+
+> 先查看当前数据源中有哪些订单相关表，和我确认销售额、支付订单数的统计口径，再保存为可复用的业务定义。
+
+需要报告时，直接说明希望的内容：
+
+> 将这次分析整理为一份报告，包含结论、关键指标、趋势图、渠道对比表和来源说明，并提供可下载的 HTML。
+
+### 3. 浏览和引用业务定义
+
+点击会话标题旁的“语义层”，按分类或关键词查找指标、维度等对象，查看业务定义和对象关系。
+这里展示已有定义；浏览页面不会执行分析查询。浏览页固定属于入口所在会话的工作区，支持把语义对象独立打开。
+
+在聊天输入框输入 `@` 可搜索并选择当前工作区的对象；多词搜索可输入 `@"monthly revenue"`。
+选中后将显示完整的 `kind:path` 引用，便于 Agent 使用你指定的对象开展分析。
+
+### 4. 阅读、调整和追问报告
+
+当前会话交付新报告后，右侧自动打开该次交付的固定版本；后台完成、历史回放和重连不会抢占阅读页面。
+同工作区的后台交付会更新已打开的报告目录，并在 current 页提示新版本，保留正在阅读的内容。
+报告生成后自动在右侧 tab 打开固定版本，主对话不附加报告 block。默认只保存 JSON，点击下载或显式调用导出工具时才生成 HTML。“报告”目录按标题查找并打开 current；可以并排阅读不同报告和版本。
+
+用户要求离线 HTML 文件时，DSH 可直接调用 `marivo_export_html({ report_id, build_id?, output_path })`，例如输出到 `reports/analysis.html`。省略 `build_id` 时固定调用开始时的 current；指定时导出该历史版本。输出是完整、自包含且可交互的报告，不含未保存编辑或临时筛选。路径必须位于当前 Workspace，已有文件不会覆盖；导出不需要 Python、数据源或发布配置。成功返回实际路径、Build ID、字节数和 SHA-256；DSH 随后通过原生 `present({ files: [{ path, description }] })` 交付该文件。
+发现新版本时 current 先提示，点击刷新或重新打开才切换，旧版本筛选随切换重置。
+没有活动会话时，侧栏的“报告”入口仍可阅读 Workspace 中的报告。
+
+- **探索数据**：筛选图表和表格，调整支持的图形及展示字段。交互使用报告中已保存的数据；获取新数据或重新计算时，在会话中提出要求。
+- **查看来源**：查看报告内容附带的来源信息，核对分析依据。
+- **调整呈现**：从 current 页点击“编辑报告”，在原编辑窗口编辑标题、正文、指标标签和图表／表格配置，移动或删除内容，支持撤销、重做和保存。
+- **继续追问**：在支持的报告内容菜单中选择“加入提问”，在输入框插入 `# <cell名称>` 引用标签，补充问题后发送；完整上下文会随引用一起提交。
+- **查看历史**：保存编辑后可在历史侧栏查看和下载已保存的版本，历史版本只读。
+
+页面筛选不会重新计算指标卡，也不会写入保存的报告。希望保留当前筛选结果时，使用“导出当前视图”。
+
+### 5. 下载与分享
+
+报告右上角的导出菜单提供两种方式：
+
+| 选项 | 适合的用途 |
+| --- | --- |
+| 下载完整报告 | 下载所查看版本的完整 HTML 报告，供离线阅读 |
+| 导出当前视图 | 将当前筛选、图形和表格排序固定为 HTML，附带来源版本及导出时间，分享当前看到的内容 |
+
+编辑模式下，请先保存或取消编辑再导出。下载的文件可直接用浏览器打开。
+
+## 许可证
+
+本项目采用 [MIT License](LICENSE)。
+
+## 报告发布到对象存储
+
+通过 `reportPublishing.enabled` 开启 S3 兼容对象存储发布；在“数据源与凭证”管理独立 AK/SK 和可选 Token。开启后报告菜单的完整 HTML 与当前视图下载均替换为发布，成功返回链接。配置示例与边界见[报告 HTML 发布](../../docs/modules/report-publishing.md)。

package/cordis.patch.yml

@@ -1,5 +1,5 @@
 # Web-profile Marivo disclosure layer. One profile-owned plugin installation
-# serves every Agent and session Workspace in native, code, or both mode.
+# serves every Agent and session Workspace in native, ptc, or both mode.
 
 - insert:
     - id: dsh-data-analysis

package/lib/bin/environment.js

@@ -5,9 +5,9 @@ import { MarivoEnvironmentError } from "../environment/errors.js";
 import { ensureSharedMarivoRuntime, MarivoWorkspaceEnvironmentManager, } from "../environment/index.js";
 import { environmentPayload } from "../environment/summary.js";
 function usage() {
-    return `Usage: dsh-data-analysis-env [--project-root PATH] [--python PATH] [--runtime-root PATH] [--uv PATH]
+    return `Usage: dsh-data-analysis-env [--project-root PATH] [--python PATH] [--runtime-root PATH] [--bootstrap-python PATH]
 
-Ensures the shared pinned Marivo and report-kit Runtime, initializes the minimal
+Ensures the shared pinned Marivo and presentation-kit Runtime, initializes the minimal
 Workspace layout, and checks the exact interpreter, import identities, and doctor
 admission used by the DSH plugin. The JSON output contains no credentials or raw
 doctor details.
@@ -23,7 +23,7 @@ function parseArguments(argv) {
     let projectRoot = process.env.DSH_DATA_ANALYSIS_PROJECT_ROOT ?? process.env.DSH_CWD ?? process.cwd();
     let pythonExecutable = process.env.DSH_DATA_ANALYSIS_PYTHON;
     let runtimeRoot = process.env.DSH_DATA_ANALYSIS_RUNTIME_ROOT;
-    let uvExecutable = process.env.DSH_DATA_ANALYSIS_UV;
+    let bootstrapPythonExecutable = process.env.DSH_DATA_ANALYSIS_BOOTSTRAP_PYTHON;
     for (let index = 0; index < argv.length; index++) {
         const option = argv[index];
         if (option === '--help' || option === '-h')
@@ -43,8 +43,8 @@ function parseArguments(argv) {
             index++;
             continue;
         }
-        if (option === '--uv') {
-            uvExecutable = requireValue(argv, index, option);
+        if (option === '--bootstrap-python') {
+            bootstrapPythonExecutable = requireValue(argv, index, option);
             index++;
             continue;
         }
@@ -54,7 +54,7 @@ function parseArguments(argv) {
         projectRoot,
         ...(pythonExecutable === undefined ? {} : { pythonExecutable }),
         ...(runtimeRoot === undefined ? {} : { runtimeRoot }),
-        ...(uvExecutable === undefined ? {} : { uvExecutable }),
+        ...(bootstrapPythonExecutable === undefined ? {} : { bootstrapPythonExecutable }),
     };
 }
 async function main(argv) {
@@ -74,7 +74,9 @@ async function main(argv) {
         const runtime = await ensureSharedMarivoRuntime({
             ...(args.pythonExecutable === undefined ? {} : { pythonExecutable: args.pythonExecutable }),
             ...(args.runtimeRoot === undefined ? {} : { runtimeRoot: args.runtimeRoot }),
-            ...(args.uvExecutable === undefined ? {} : { uvExecutable: args.uvExecutable }),
+            ...(args.bootstrapPythonExecutable === undefined
+                ? {}
+                : { bootstrapPythonExecutable: args.bootstrapPythonExecutable }),
         });
         const manager = new MarivoWorkspaceEnvironmentManager(runtime);
         const environment = await manager.resolve(args.projectRoot);

package/lib/bin/presentation-lint.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import process from 'node:process';
+import { lintPresentationDraft } from "../presentation/lint.js";
+const usage = 'Usage: dsh-data-analysis-presentation-lint DRAFT_PATH [--project-root PATH]\n';
+const args = process.argv.slice(2);
+if (args.length === 1 && (args[0] === '--help' || args[0] === '-h')) {
+    process.stdout.write(usage);
+}
+else if ((args.length !== 1 && args.length !== 3) ||
+    !args[0] ||
+    args[0].startsWith('-') ||
+    (args.length === 3 && (args[1] !== '--project-root' || !args[2]))) {
+    process.stderr.write(usage);
+    process.exitCode = 2;
+}
+else {
+    const result = await lintPresentationDraft(path.resolve(args[2] ?? process.cwd()), args[0]);
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    process.exitCode = result.ok ? 0 : 1;
+}

package/lib/bridges.js

@@ -1,11 +1,11 @@
 import { MarivoDatasourceBridge } from "./datasource/bridge.js";
 import { MarivoHelpBridge } from "./disclosure/bridge.js";
-import { MarivoEvidenceBridge } from "./evidence/bridge.js";
+import { MarivoPresentationProjection } from "./presentation/projection/index.js";
 /** Compose domain adapters without adding domain methods back to the Environment. */
 export function createMarivoBridgeSet(environment) {
     return Object.freeze({
         help: new MarivoHelpBridge(environment),
         datasource: new MarivoDatasourceBridge(environment),
-        evidence: new MarivoEvidenceBridge(environment),
+        presentation: new MarivoPresentationProjection(environment),
     });
 }

package/lib/client/credentials/changes.js

@@ -0,0 +1,74 @@
+import { credentialChangesRemote, } from "../../datasource/changes-contract.js";
+/** Mount before opening a logical stream, using the existing Gateway WebSocket. */
+export function credentialChanges(ctx) {
+    const mounted = ctx.remote.$mount(credentialChangesRemote);
+    // Initialization may be withdrawn before a Session starts consuming the mount.
+    void mounted.catch(() => { });
+    ctx.effect(() => async () => (await mounted)());
+    // Host and browser Context augmentations share this build; use the browser contract here.
+    const connection = ctx.connection;
+    return (sessionId) => {
+        let snapshot;
+        const stopConnection = connection.generation.subscribe(() => {
+            if (!connection.generation.getSnapshot())
+                snapshot?.abort();
+        });
+        const stream = ctx.remote.$stream({
+            name: 'dsh-data-analysis credential changes',
+            async *open(signal) {
+                const current = new AbortController();
+                snapshot = current;
+                try {
+                    await mounted;
+                    signal.throwIfAborted();
+                    // A dynamically mounted namespace needs its own declared Cordis consumer.
+                    let namespace;
+                    const consumer = ctx.inject(['remote.dshDataAnalysisCredentials'], (scoped) => {
+                        namespace = scoped.remote.dshDataAnalysisCredentials;
+                    });
+                    const stop = () => {
+                        void consumer.dispose();
+                    };
+                    signal.addEventListener('abort', stop, { once: true });
+                    if (signal.aborted)
+                        stop();
+                    try {
+                        await consumer;
+                        signal.throwIfAborted();
+                        if (!namespace)
+                            throw new Error('credential-notification-unavailable');
+                        yield* namespace.changes(sessionId, signal);
+                    }
+                    finally {
+                        // Abort snapshots before RemoteStream starts waiting for reconnection.
+                        current.abort();
+                        signal.removeEventListener('abort', stop);
+                        await consumer.dispose();
+                    }
+                }
+                finally {
+                    current.abort();
+                }
+            },
+            carrierFailed: () => snapshot?.abort(),
+            ended: () => new Error('credential-notification-ended'),
+        });
+        const dispose = async () => {
+            stopConnection();
+            snapshot?.abort();
+            await stream.dispose();
+        };
+        return {
+            async *[Symbol.asyncIterator]() {
+                try {
+                    for await (const item of stream)
+                        yield { ...item, signal: AbortSignal.any([item.signal, snapshot.signal]) };
+                }
+                finally {
+                    await dispose();
+                }
+            },
+            dispose,
+        };
+    };
+}

package/lib/client/credentials/create-datasource.js

@@ -0,0 +1,171 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// @ts-nocheck -- JSX is bundled by the plugin client build.
+import { useEffect, useId, useRef, useState } from 'react';
+import { useCopy } from "./../i18n/context.js";
+import { errorMessage, message } from "./../i18n/copy.js";
+import { credentialReference, prepareCredentials } from "./credential-draft.js";
+import { creationFieldValues } from "./defaults.js";
+import { datasourceDescription } from "./descriptions.js";
+function credentialLabel(field) {
+    return ({
+        user_env: 'marivo.credentials.username',
+        password_env: 'marivo.credentials.password',
+        http_bearer_token_env: 'marivo.credentials.access-token',
+        http_headers_env: 'marivo.credentials.header-credential-value',
+    }[field] ?? field.replace(/_env$/, ''));
+}
+function credentialRows(schema, backend, values = {}) {
+    return (schema.backends.find((item) => item.name === backend)?.fields ?? [])
+        .filter((field) => field.name.endsWith('_env'))
+        .flatMap((field) => field.type === 'json'
+        ? Object.entries(values[field.name] ?? {}).map(([key, existing]) => ({
+            id: crypto.randomUUID(),
+            field: field.name,
+            key,
+            existing,
+            value: '',
+        }))
+        : [{ id: crypto.randomUUID(), field: field.name, existing: values[field.name], value: '' }]);
+}
+export function CreateDatasource({ model, workspaceId, close, name, requestId }) {
+    const t = useCopy();
+    const formId = useId();
+    const active = useRef(false);
+    const [schema, setSchema] = useState(null);
+    const [original, setOriginal] = useState(null);
+    const [backend, setBackend] = useState('');
+    const [values, setValues] = useState({});
+    const [credentials, setCredentials] = useState([]);
+    const [busy, setBusy] = useState(false);
+    const [error, setError] = useState('');
+    useEffect(() => {
+        const controller = new AbortController();
+        active.current = true;
+        Promise.all([
+            model.authoring(workspaceId, controller.signal, name ? 'edit' : 'create'),
+            name ? model.configuration(workspaceId, name, controller.signal) : Promise.resolve(null),
+        ])
+            .then(([value, configuration]) => {
+            if (controller.signal.aborted)
+                return;
+            setSchema(value);
+            setOriginal(configuration);
+            setBackend(configuration?.backend ?? value.backends[0]?.name ?? '');
+            setCredentials(credentialRows(value, configuration?.backend ?? value.backends[0]?.name, configuration?.fields));
+            if (!configuration)
+                setValues(creationFieldValues(value, value.backends[0]?.name ?? ''));
+            if (configuration) {
+                const fields = value.backends.find((item) => item.name === configuration.backend)?.fields;
+                if (!fields)
+                    throw new Error('marivo.credentials.this-runtime-cannot-fully-edit-this-datasource');
+                setValues(Object.fromEntries(fields
+                    .filter((field) => !field.name.endsWith('_env') && configuration.fields[field.name] !== undefined)
+                    .map((field) => [
+                    field.name,
+                    field.type === 'string'
+                        ? configuration.fields[field.name]
+                        : JSON.stringify(configuration.fields[field.name]),
+                ])));
+            }
+        })
+            .catch((error) => {
+            if (!controller.signal.aborted)
+                setError(errorMessage(error));
+        });
+        return () => {
+            active.current = false;
+            controller.abort();
+        };
+    }, [model, workspaceId, name]);
+    const fields = schema?.backends.find((item) => item.name === backend)?.fields ?? [];
+    const credentialFields = fields.filter((field) => field.name.endsWith('_env'));
+    const updateCredential = (id, change) => setCredentials((rows) => rows.map((row) => (row.id === id ? { ...row, ...change } : row)));
+    async function submit(event) {
+        event.preventDefault();
+        if (busy)
+            return;
+        setError('');
+        const input = {};
+        let changes = {};
+        try {
+            for (const field of fields.filter((field) => !field.name.endsWith('_env'))) {
+                const value = values[field.name];
+                if (value === undefined)
+                    continue;
+                if (value === '' &&
+                    (field.type !== 'string' ||
+                        (name
+                            ? original?.fields[field.name] !== ''
+                            : schema.creationDefaults?.[backend]?.[field.name] !== '')))
+                    continue;
+                input[field.name] = field.type === 'string' ? value : JSON.parse(value);
+            }
+            const prepared = prepareCredentials(input.name ?? '', credentials);
+            Object.assign(input, prepared.fields);
+            changes = prepared.changes;
+        }
+        catch (error) {
+            setError(error instanceof SyntaxError
+                ? 'marivo.credentials.check-the-format-of-number-boolean-and-json-fields'
+                : errorMessage(error));
+            return;
+        }
+        setBusy(true);
+        // Remove secrets from mounted inputs as soon as the explicit submission begins.
+        setCredentials((rows) => rows.map((row) => ({ ...row, value: '' })));
+        try {
+            await model.saveConfiguration(workspaceId, schema, { backend, fields: input }, original, requestId, changes);
+            if (active.current)
+                close();
+        }
+        catch (error) {
+            if (active.current)
+                setError(message('marivo.credentials.value-credential-inputs-have-been-cleared-enter-them-again', {
+                    p0: errorMessage(error),
+                }));
+        }
+        finally {
+            for (const ref of Object.keys(changes))
+                delete changes[ref];
+            if (active.current)
+                setBusy(false);
+        }
+    }
+    return (_jsxs("form", { className: "mc-form", "aria-label": name ? t('marivo.credentials.edit-datasource') : t('marivo.credentials.add-datasource'), onSubmit: submit, children: [_jsxs("div", { className: "mc-form-body", children: [_jsx("div", { className: "mc-detail-heading", children: _jsx("h3", { children: name
+                                ? t('marivo.credentials.edit-datasource')
+                                : t('marivo.credentials.add-datasource') }) }), error && (_jsx("p", { role: "alert", className: "mc-result", "data-tone": "error", children: t(error) })), !schema && !error && (_jsx("p", { role: "status", children: t('marivo.credentials.loading-datasource-configuration-fields') })), schema && (_jsxs("fieldset", { className: "mc-field", disabled: busy, children: [_jsxs("label", { className: "mc-secret-input", children: [t('marivo.credentials.engine'), _jsx("select", { "aria-label": t('marivo.credentials.engine'), disabled: !!name, value: backend, onChange: (event) => {
+                                            setBackend(event.target.value);
+                                            setValues(creationFieldValues(schema, event.target.value));
+                                            setCredentials(credentialRows(schema, event.target.value));
+                                            setError('');
+                                        }, children: schema.backends.map((item) => (_jsx("option", { value: item.name, children: item.name }, item.name))) })] }), fields
+                                .filter((field) => !field.name.endsWith('_env'))
+                                .map((field) => (_jsxs("label", { className: "mc-secret-input", htmlFor: `${formId}-${field.name}`, children: [_jsxs("span", { className: "mc-input-heading", children: [_jsxs("span", { className: "mc-input-name", children: [field.name, field.required ? ' *' : ''] }), field.description && (_jsx("span", { className: "mc-input-description", children: t(datasourceDescription(field.description)) }))] }), field.type === 'boolean' ? (_jsxs("select", { id: `${formId}-${field.name}`, "aria-label": field.name, value: values[field.name] ?? '', onChange: (event) => setValues({ ...values, [field.name]: event.target.value }), children: [_jsxs("option", { value: "", children: [t('marivo.credentials.default'), field.default == null ? '' : ` (${field.default})`] }), _jsx("option", { value: "true", children: "true" }), _jsx("option", { value: "false", children: "false" })] })) : (_jsx("input", { id: `${formId}-${field.name}`, "aria-label": field.name, required: field.required, disabled: !!name && field.name === 'name', autoComplete: "off", type: field.type === 'number' ? 'number' : 'text', placeholder: field.default == null
+                                            ? field.type === 'json'
+                                                ? 'JSON'
+                                                : ''
+                                            : String(field.default), value: values[field.name] ?? '', onChange: (event) => setValues({ ...values, [field.name]: event.target.value }) }))] }, field.name))), credentialFields.length > 0 && (_jsxs("section", { className: "mc-inline-credentials", "aria-label": t('marivo.credentials.connection-credentials'), children: [_jsx("h4", { children: t('marivo.credentials.connection-credentials') }), _jsxs("p", { className: "mc-note", children: [t('marivo.credentials.enter-credential-values-directly-for-harness-to-save-references'), name ? t('marivo.credentials.leave-blank-to-keep-the-current-value-a-new') : ''] }), credentialFields.map((field) => (_jsxs("div", { className: "mc-credential-group", children: [credentials
+                                                .filter((row) => row.field === field.name)
+                                                .map((row) => {
+                                                const label = credentialLabel(field.name);
+                                                const reference = credentialReference(values.name ?? '', row);
+                                                return (_jsxs("div", { className: "mc-credential-entry", children: [row.key !== undefined && (_jsxs("label", { className: "mc-secret-input", children: [t('marivo.credentials.header-name'), _jsx("input", { "aria-label": t('marivo.credentials.header-name'), value: row.key, onChange: (event) => updateCredential(row.id, { key: event.target.value }) })] })), _jsxs("label", { className: "mc-secret-input", children: [_jsxs("span", { className: "mc-input-heading", children: [_jsxs("span", { className: "mc-input-name", children: [t(label), field.required ? ' *' : ''] }), _jsx("span", { className: "mc-input-description", children: row.existing
+                                                                                ? t('marivo.credentials.a-reference-is-configured-leave-blank-to-keep-it')
+                                                                                : t('marivo.credentials.enter-the-value-directly-no-need-to-create-a') })] }), _jsx("input", { "aria-label": t(label), type: "password", autoComplete: "new-password", maxLength: 65536, required: field.required && !reference, value: row.value, placeholder: row.existing
+                                                                        ? t('marivo.credentials.leave-blank-to-keep-enter-a-new-value-to')
+                                                                        : t('marivo.credentials.enter-credential-value'), onChange: (event) => updateCredential(row.id, { value: event.target.value }) })] }), _jsxs("details", { className: "mc-reference-options", children: [_jsx("summary", { children: t('marivo.credentials.credential-reference-review-or-change') }), _jsxs("label", { className: "mc-secret-input", children: [field.name, _jsx("input", { "aria-label": field.name, autoComplete: "off", value: reference, placeholder: t('marivo.credentials.generated-after-entering-a-credential-value'), onChange: (event) => updateCredential(row.id, { reference: event.target.value }) })] }), _jsx("p", { className: "mc-note", children: t('marivo.credentials.to-reuse-a-saved-credential-enter-its-reference-and') }), row.reference !== undefined && (_jsx("button", { type: "button", onClick: () => updateCredential(row.id, { reference: undefined }), children: t('marivo.credentials.restore-automatic-reference') }))] }), row.key !== undefined && (_jsx("button", { type: "button", className: "mc-quiet", onClick: () => setCredentials((rows) => rows.filter((item) => item.id !== row.id)), children: t('marivo.credentials.remove-header') }))] }, row.id));
+                                            }), field.type === 'json' && (_jsx("button", { type: "button", onClick: () => setCredentials((rows) => [
+                                                    ...rows,
+                                                    { id: crypto.randomUUID(), field: field.name, key: '', value: '' },
+                                                ]), children: t('marivo.credentials.add-header-credential') }))] }, field.name)))] }))] }))] }), _jsx("p", { className: "mc-note", children: requestId
+                    ? t('marivo.credentials.save-configuration-and-credentials-then-test-the-connection-the')
+                    : name
+                        ? t('marivo.credentials.test-the-connection-again-after-saving-name-and-engine')
+                        : '' }), _jsxs("div", { className: "mc-form-footer", children: [_jsx("button", { className: "mc-primary", type: "submit", disabled: !backend || busy, children: busy
+                            ? t('marivo.credentials.saving-or-validating')
+                            : requestId
+                                ? t('marivo.credentials.save-and-test-then-continue')
+                                : name
+                                    ? t('marivo.credentials.save-configuration')
+                                    : t('marivo.credentials.confirm-new-datasource') }), _jsx("button", { type: "button", onClick: close, disabled: busy, children: t('marivo.credentials.cancel') })] })] }));
+}

package/lib/client/credentials/credential-draft.js

@@ -0,0 +1,42 @@
+export function credentialReference(name, draft) {
+    if (draft.reference !== undefined)
+        return draft.reference.trim();
+    if (!draft.value)
+        return draft.existing ?? '';
+    const part = (value) => value
+        .toUpperCase()
+        .replace(/[^A-Z0-9_]/g, '_')
+        .slice(0, 40);
+    return `DS_${part(name) || 'CONNECTION'}_${part(draft.key ?? draft.field.replace(/_env$/, ''))}_${draft.id.replace(/-/g, '').toUpperCase()}`;
+}
+/** Values are kept separate from the public configuration, then handed to the credential operation. */
+export function prepareCredentials(name, drafts) {
+    const fields = {};
+    const changes = Object.create(null);
+    for (const draft of drafts) {
+        const ref = credentialReference(name, draft);
+        if (!ref && !draft.value)
+            continue;
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(ref) ||
+            ref.length > 256 ||
+            /^(MARIVO_|DSH_DATA_ANALYSIS_|DSH_HOME$|DSH_SESSION_ID$|DSH_SESSION_JSONL$|DSH_SHELL$)/i.test(ref))
+            throw new Error('marivo.credentials.credential-references-may-contain-only-letters-numbers-and-underscores');
+        if (draft.key !== undefined) {
+            if (!draft.key.trim())
+                throw new Error('marivo.credentials.enter-the-header-name-for-this-credential');
+            fields[draft.field] ??= Object.create(null);
+            const mapping = fields[draft.field];
+            if (Object.hasOwn(mapping, draft.key))
+                throw new Error('marivo.credentials.header-names-must-be-unique');
+            mapping[draft.key] = ref;
+        }
+        else
+            fields[draft.field] = ref;
+        if (draft.value) {
+            if (changes[ref] !== undefined && changes[ref] !== draft.value)
+                throw new Error('marivo.credentials.the-same-credential-reference-cannot-have-different-values');
+            changes[ref] = draft.value;
+        }
+    }
+    return { fields, changes };
+}

package/lib/client/credentials/defaults.js

@@ -0,0 +1,11 @@
+export function creationFieldValues(schema, backend) {
+    const defaults = schema.creationDefaults?.[backend] ?? {};
+    return Object.fromEntries((schema.backends.find((item) => item.name === backend)?.fields ?? [])
+        .filter((field) => !field.name.endsWith('_env') && Object.hasOwn(defaults, field.name))
+        .map((field) => [
+        field.name,
+        field.type === 'string'
+            ? defaults[field.name]
+            : JSON.stringify(defaults[field.name]),
+    ]));
+}