@chengxianglibra/dsh-data-analysis 0.1.2 → 0.2.1

package/README.en.md

@@ -0,0 +1,135 @@
+# @chengxianglibra/dsh-data-analysis
+
+[简体中文](README.md) | English
+
+Analyze data with natural language in [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).
+Explore and reuse business metric definitions, then turn your findings into interactive charts, reports,
+and dashboards that you can also read offline. Semantic analysis is powered by [Marivo](https://github.com/chengxianglibra/marivo).
+
+This is an independently maintained community plugin. It is not an official DeepSeek product.
+
+## Capabilities and features
+
+| What you want to do | What the plugin offers |
+| --- | --- |
+| Answer business questions | Analyze metric trends, compare periods or business segments, and explore reasons for changes using natural language |
+| Analyze local files | Upload files or use files in your workspace to analyze data and create charts and reports |
+| Connect to data | Configure data sources, manage credentials, and test connections; DuckDB, Trino, and ClickHouse are supported by default |
+| Keep definitions consistent | Work with the assistant to define and reuse metrics and dimensions, and explore their relationships |
+| Specify what to analyze | Search for and reference existing semantic objects with `@` in the chat input |
+| Present findings | Create reports and dashboards with conclusions, metric cards, charts, tables, and source information |
+| Explore further | Filter interactively, adjust the presentation, and reference report content in follow-up questions |
+| Read and share | Save and browse previous versions, and download HTML for offline reading and sharing |
+
+## Installation
+
+### Prerequisites
+
+- Node.js `^22.19.0 || >=24.0.0`: version 22.19.0 or later in the 22.x series, or version 24.0.0 and above. Version 23.x is not supported.
+- DeepSeek Harness `>=0.1.5-rc.1`, installed and configured.
+- `pnpm` available on the command line for Harness to install the plugin.
+- Python 3.10+, available as `python3` (`python` on Windows), with `venv`/`ensurepip` support. Some Linux distributions require the additional `python3-venv` package.
+
+You do not need to install Marivo beforehand. The analysis environment is prepared automatically on first launch.
+An internet connection is required to download dependencies; wait for setup to finish.
+
+### Install and launch
+
+Install the plugin into the Web Profile:
+
+```bash
+dsh plugin --profile web add @chengxianglibra/dsh-data-analysis
+```
+
+Start the Web Profile after installation. If it is already running, exit and restart it:
+
+```bash
+dsh --profile web
+```
+
+In the Web interface, select a Workspace, create a session, and send a message.
+Data Sources (数据源), Semantic Layer (语义层), and Reports (报告) appear beside the session title and open in tabs on the right.
+The examples below use the Web interface; Chinese labels are included to help you locate the controls.
+
+## How to use
+
+### 1. Prepare your data
+
+**Local files**: Upload a file and ask a question, or specify a file already in your workspace.
+No data source configuration or business definitions are required first.
+CSV, JSON, Parquet, and Excel `.xlsx` files are supported. Reading `.xlsx` for the first time requires an internet connection to download an extension.
+Convert older `.xls` files to `.xlsx`, CSV, or Parquet first.
+
+**Databases**: Open Data Sources (数据源) beside the session title to view connections and their configuration status in the current workspace:
+
+1. Select Add Data Source (新增数据源), choose an engine, and enter a name and connection details.
+2. If authentication is required, enter the username, password, or token under Connection Credentials (连接凭证).
+3. Save and test the connection. Use the result to check the address, credentials, or access permissions.
+
+Use Edit Configuration (编辑配置) to update an existing connection. Its name and engine stay fixed; test the connection again after saving.
+Saved credential values are not displayed; leave them blank to keep using them. Submit passwords and tokens through the credential form, not in chat messages.
+
+If a data source needs to be added or repaired during analysis, the assistant can open the configuration page.
+Enter a new connection or choose Use Existing Data Source (使用已有数据源), then select Save and Test, Continue on Success (保存并测试，成功后继续).
+The assistant resumes analysis after verifying the connection and access to the target data.
+
+### 2. Ask questions in natural language
+
+Describe the data, time range, metric definitions, and results you want. For example:
+
+> Using the order data, analyze revenue and order count for August 2026, compare them with July, break them down by channel, and explain the sources and metric definitions.
+
+> Check query duration over the last seven days. Identify the slowest query types and provide a trend chart and a detailed table.
+
+If you have not yet defined your business metrics, start by asking the assistant to help:
+
+> First, find order-related tables in the current data source. Confirm the definitions of revenue and paid order count with me, then save them as reusable business definitions.
+
+When you need a report, describe its contents:
+
+> Turn this analysis into a report with conclusions, key metrics, trend charts, a channel comparison table, and source information. Provide a downloadable HTML file.
+
+### 3. Browse and reference business definitions
+
+Open Semantic Layer (语义层) to find metrics, dimensions, and other objects by category or keyword,
+and inspect their definitions and relationships. Open objects separately to compare them side by side.
+
+Type `@` in the chat input to search for and select objects in the current workspace.
+For a multiword search, use `@"monthly revenue"`. Ask questions about the selected objects to keep the analysis aligned with your business definitions.
+
+### 4. Read, edit, and ask follow-up questions about reports
+
+When the current session delivers a new report, it opens automatically on the right.
+Use the Reports (报告) catalog to find reports by title and read different reports or versions side by side.
+The page notifies you when a new version is available, so you can choose when to switch.
+You can also read workspace reports from the Reports sidebar entry without an active session.
+
+- **Explore data**: Filter charts and tables, and adjust supported chart types and displayed fields. Interactions use data already saved in the report; ask in chat to fetch fresh data or recalculate results.
+- **Check sources**: Inspect the source information attached to report content to review the basis of the analysis.
+- **Edit the presentation**: On the latest version page, select Edit Report (编辑报告) to change titles, text, metric labels, and chart or table settings. Move or remove content, undo or redo changes, and save your edits.
+- **Ask follow-up questions**: Choose Add to Question (加入提问) from a supported report content menu to insert a reference into the chat input, then add your question and send it.
+- **Browse history**: After saving edits, use the history sidebar to view and download saved versions. Historical versions are read-only.
+
+Page filters do not recalculate metric cards or change the saved report. To preserve the current filtered view, use Export Current View (导出当前视图).
+
+### 5. Download and share
+
+The export menu at the top right of a report offers two options:
+
+| Option | Use it to |
+| --- | --- |
+| Download Full Report (下载完整报告) | Download the complete HTML report for the version you are viewing and read it offline |
+| Export Current View (导出当前视图) | Capture the current filters, charts, and table sorting in HTML, with the source version and export time, to share what you see |
+
+You can also ask the assistant to export a report as an HTML file. Open downloaded files in a browser to read and interact with them offline, without connecting to the original data source.
+If you are editing a report, save or cancel your edits before exporting.
+
+## Analysis timeout
+
+Go to Settings → Plugins → Plugin Configuration → Data Analysis (设置 → 插件 → 插件配置 → 数据分析)
+to adjust the default timeout for Python analysis. The default is 120 seconds, and changes apply to the next analysis call after saving.
+The actual execution limit is still subject to Harness execution policies.
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

package/README.md

@@ -1,121 +1,128 @@
 # @chengxianglibra/dsh-data-analysis
 
-由个人维护的 DeepSeek Harness 社区插件，并非 DeepSeek 官方发行或维护的软件包。
+简体中文 | [English](README.en.md)
 
-DeepSeek Harness 的 Marivo 集成插件。当前包提供：
+在 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 中，用自然语言完成数据分析，
+浏览和复用业务指标定义，并将结果整理为可交互、可离线阅读的图表、报告和看板。
+语义分析能力由 [Marivo](https://github.com/chengxianglibra/marivo) 提供。
 
-- 精确 Marivo 0.5.4 共享 Runtime 与 zero-init per-Workspace binding；
-- `marivo_help` 实时公共 Help transport；
-- 会话标题旁的“语义层”对象浏览器：Workspace 分类搜索、只读详情与局部关系图；
-- `marivo_datasource_test` 的 DSH Credentials 收集与显式 connection test；
-- `marivo_python` 的本次执行准入与单次 resolver 凭证注入；
-- 会话标题旁的“数据源与凭证”管理、测试与缺失输入提交后的原调用续接；
-- `marivo_present({ draft_path })` 的一次文件提交、结果卡片、打开与离线 HTML 下载；
-- 唯一插件 Skill `dsh-data-analysis-presentation`，组织图表、表格、报告、看板与可读来源展示；
-- `dsh_data_analysis_presentation.write_dataset(frame, path)` 的 computed typed JSON writer；
-- 内部 Artifact/computed/source-only 数据投影，保存精确来源及 unavailable 状态。
+本项目是个人维护的社区插件，并非 DeepSeek 官方发行或维护的软件。
 
-共享 reader、离线 builder、`marivo_present` 和展示 Skill 提供统一的展示交付；
-两个 Marivo Runtime Skill `marivo-analysis`、`marivo-semantic` 继续从当前 Runtime 挂载。
-旧 report-kit、report Skill、经典 JS 与 Evidence 卡协议不再分发。升级说明见
-[0.1.2 发布说明](../../docs/releases/0.1.2.md)。
+## 能力与特性
 
-## Compatibility
+| 你想做什么 | 插件提供的能力 |
+| --- | --- |
+| 回答业务问题 | 用自然语言分析指标趋势、比较不同时间或业务分组、探索变化原因 |
+| 分析本地文件 | 上传文件或指定工作区中的文件，直接分析并生成图表、报告 |
+| 连接数据 | 配置数据源、管理连接凭证并测试连接；默认支持 DuckDB、Trino、ClickHouse |
+| 统一分析口径 | 与助手一起整理和复用指标、维度等业务定义，浏览对象及其关系 |
+| 明确分析对象 | 在输入框通过 `@` 搜索并引用已有语义对象 |
+| 展示分析结果 | 生成包含结论、指标卡、图表、表格和来源说明的报告或看板 |
+| 继续探索 | 交互筛选、调整呈现，并引用报告内容继续提问 |
+| 阅读与分享 | 保存和查看历史版本，下载 HTML 供离线阅读与分享 |
 
-包内 `dshDataAnalysisCompatibility` 是唯一运行时兼容声明：
+## 安装
 
-- DSH distribution 与所有必需 peer 精确使用 `0.1.1-rc.2`；
-- Runtime 通过 pip 安装已发布的 Marivo 0.5.4；版本约束为 `marivo[duckdb,trino,clickhouse]==0.5.4`；
-- 项目自有 Runtime marker 为 `dsh-data-analysis-runtime/v3`；
-- 子进程策略为 `direct-argv-inherited-env-snapshot-overlay-v2`。
+### 环境准备
 
-管理员解释器的 `marivo.__version__` 与 package identity 必须精确匹配；不使用 capability/version matrix。
+- Node.js `^22.19.0 || >=24.0.0`：22.x 需至少 22.19.0，或使用 24.0.0 及以上版本；不支持 23.x。
+- 已安装并配置好 DeepSeek Harness `>=0.1.5-rc.1`。
+- 命令行中可使用 `pnpm`，供 Harness 安装插件。
+- Python 3.10+，命令行可运行 `python3`（Windows 为 `python`），且支持 `venv`/`ensurepip`；部分 Linux 发行版需额外安装 `python3-venv`。
 
-## Tool contracts
+无需预装 Marivo。首次启动会自动准备分析环境，需要联网下载依赖，请等待准备完成。
 
-```text
-marivo_help({ targets: string[] })
-marivo_datasource_test({ name: string })
-marivo_python({ code: string, datasources: string[] })
-marivo_present({ draft_path: string, report_id?: string, expected_build_id?: string })
+### 安装并启动
+
+将插件安装到 Web Profile：
+
+```bash
+dsh plugin --profile web add @chengxianglibra/dsh-data-analysis
 ```
 
-`marivo_datasource_test` 只拥有缺失 Credentials 的 DSH/Web 闭环和显式连接测试；
-`marivo_python` 在本次调用内等待全部数据源凭证就绪、核验身份并取得 fresh snapshot，再通过 DSH 前台
-执行服务与 Marivo 公开 resolver 启动一次代码。配置齐全时不额外测试；普通 Shell 不获得凭证。
-缺失输入时默认等待 Web 表单，提交测试成功后继续原调用；取消、轮换或 Workspace 变化终止旧准备，
-已启动代码失败不重放。无 Web 场景配置 `credentialInteraction: 'none'`，subagent 同样不等待表单。
-详见[凭证模块](../../docs/modules/datasource-credentials.md)。`md.inspect(...)`、
-Session recovery、Artifact revalidation、Quality、Evidence 读取、Session Graph 与 `to_pandas()` 都直接使用
-Marivo 公共 API，不增加 convenience Tool。
-
-## 语义层对象浏览器
-
-点击 DSH 会话标题旁的“语义层”，默认查看该会话所属 Workspace，也可在面板内显式切换 Workspace。
-可按业务域和类型筛选，搜索名称、引用与业务定义，
-复制对象引用、查看定义位置，并在对象关系中逐层浏览。桌面采用三栏布局，窄屏支持列表与详情切换。
-
-页面不要求 live Agent，只读取 Marivo Catalog 元数据，不执行 `observe`、数据预览或连接测试。
-打开和手动刷新重新加载；读取失败时明确标注上次成功内容。数据源连接配置、凭证值与原始源码不展示。
-使用及验收边界见[模块说明](../../docs/modules/semantic-browser.md)。
-
-“数据源与凭证”位于同一会话标题旁，打开时同样使用该会话所属 Workspace，面板内保留 Workspace 选择。
-两个入口随 Harness 的会话标题显示，无会话或空会话时不显示，侧栏底部不保留入口。
-
-## 分析与展示
-
-普通事实问答使用文字。图表、表格、报告、看板和可读来源展示加载 `dsh-data-analysis-presentation`，
-按 Skill 编写 Workspace 相对 Draft，再调用 `marivo_present`。已有 Artifact 或 computed 数据无需先激活
-`marivo-analysis`；需要新分析或语义编写时，按需加载对应 Runtime Skill 与 live Help。
-Skill 只指导内容组织、声明来源和交付，不承担分析计算或来源有效性判断；布局由 reader 自适应。
-完整流程见[展示 Skill](../../docs/modules/presentation-skill.md)。
-
-Python helper 的可选 `labels={列名: 展示名}` 设置中文表头、图例和 tooltip，字段绑定仍使用原列名。
-Python helper 只接受 pandas DataFrame，写入 `schemaVersion: 1` 的 typed JSON；int64/Decimal 保留精确字符串，
-null 保留缺失含义，datetime 必须带时区。它不保存来源或转换代码；来源在展示 Draft 中声明。
-固定 projection 从同一 bound Workspace 恢复 persisted Artifact 和可选 Finding，不自动 observe、revalidate 或读取凭据。
-直接 Artifact dataset 缺必要数据会失败，computed 和 source-only 可以保留 unavailable 来源。
-
-共享 reader 展示 Markdown、metric、18 类 chart、table 和 source，保留精确值、单位、截断与 unavailable 来源。chart 支持 bar/line 变体与当前页面的字段、图形及过滤探索；统计量由分析阶段准备，探索不改写保存快照。
-`marivo_present` 读取 Workspace 相对 Draft 路径，生成不可变新 build 的 JSON/自包含 HTML。
-默认创建新 Report；修改已有报告时成对传入 `report_id` 与本次修改所基于的 `expected_build_id`，以完整 Draft 更新同一 Report。
-版本冲突时读取当前保存内容并合并需保留的编辑，不强行覆盖，也不回退新建。
-原卡片通过 reportId 打开最近保存结果；阅读器可编辑标题、正文、指标标签、图表和表格配置，以及移动／删除 cell（允许删空），支持撤销／重做和保存／取消。
-保存生成同报告的新 build，保留底层数据、来源和代码，不运行 Agent 或 Python。
-全部 18 种 chart 与同 dataset 的表格和数据预览共享临时筛选；筛选不重算指标、不标记编辑修改、不进入保存、下载或打印。
-文档、receipt 与 delivery 使用 schema v2，Draft 和 typed dataset 保持 v1；旧报告不读取、不迁移，旧文件保留。文本始终包含两份文件的位置、digest 和字节数，headless 也能取得交付物。
-展开来源仅使用保存的快照；文件变化、缺失或 Workspace 归属变化会明确失败。
-实现与验收见[展示数据投影](../../docs/modules/presentation-projection.md)、[展示 reader](../../docs/modules/presentation-reader.md)、
-[展示交付](../../docs/modules/presentation-delivery.md)。
-
-## 验证
+安装后启动 Web Profile；如果已在运行，请先退出再重新启动：
 
 ```bash
-npm run check
-npm run build
-npm run verify:plugin-package
+dsh --profile web
 ```
 
-当前架构与验收边界见仓库根目录的[总体架构](../../docs/architecture.md)和
-[展示交付](../../docs/modules/presentation-delivery.md)。
+在 Web 界面选择分析使用的工作区（Workspace），新建会话并发送一条消息。
+会话标题旁会显示“数据源”“语义层”“报告”三个入口，相关页面在右侧标签页打开。以下以 Web 界面为例。
+
+## 如何使用
+
+### 1. 准备数据
+
+**本地文件**：上传文件后直接提问，或指定工作区中已有文件，无需先配置数据源或建立业务定义。
+支持 CSV、JSON、Parquet 和 Excel `.xlsx`；首次读取 `.xlsx` 需要联网下载扩展。
+旧版 `.xls` 请先转换为 `.xlsx`、CSV 或 Parquet。
+
+**数据库**：在会话标题旁打开“数据源”，查看当前工作区的连接与配置状态：
+
+1. 点击“新增数据源”，选择引擎，填写名称及连接信息。
+2. 如果需要身份认证，在“连接凭证”中填写用户名、密码或令牌。
+3. 保存并测试连接，根据结果检查地址、凭证或访问权限。
+
+已有数据源可通过“编辑配置”修改连接信息，名称和引擎保持不变；保存后重新测试。
+已保存的凭证值不会回显，留空可沿用。请通过凭证表单提交密码或令牌，不要粘贴到聊天消息中。
+
+分析过程中需要新增或修复数据源时，助手可打开配置页。你可以填写新连接，或选择“使用已有数据源”，
+点击“保存并测试，成功后继续”，连接与目标数据访问验证通过后，助手会继续分析。
+
+### 2. 用自然语言提出分析问题
+
+说明使用哪些数据、时间范围、指标口径和希望得到的结果。例如：
+
+> 使用订单数据，分析 2026 年 8 月的销售额和订单量，与 7 月比较，按渠道拆分，并说明数据来源和口径。
+
+> 检查最近七天的查询耗时，找出耗时最高的查询类型，给出趋势图和明细表。
+
+如果还没有整理业务定义，可以先让助手帮助梳理：
+
+> 先查看当前数据源中有哪些订单相关表，和我确认销售额、支付订单数的统计口径，再保存为可复用的业务定义。
+
+需要报告时，直接说明希望的内容：
+
+> 将这次分析整理为一份报告，包含结论、关键指标、趋势图、渠道对比表和来源说明，并提供可下载的 HTML。
+
+### 3. 浏览和引用业务定义
+
+点击“语义层”，按分类或关键词查找指标、维度等对象，查看业务定义和对象关系。
+支持独立打开对象，方便对照阅读。
+
+在聊天输入框输入 `@`，搜索并选择当前工作区的对象；多词搜索可输入 `@"monthly revenue"`。
+选中后即可围绕指定对象提问，让助手使用一致的业务口径开展分析。
+
+### 4. 阅读、调整和追问报告
+
+当前会话交付新报告后，会自动在右侧打开。通过“报告”目录可按标题查找报告，并排阅读不同报告和版本。
+发现新版本时，页面会提示更新，你可以选择何时切换。没有活动会话时，也可通过侧栏的“报告”入口阅读工作区中的报告。
+
+- **探索数据**：筛选图表和表格，调整支持的图形及展示字段。交互使用报告中已保存的数据；获取新数据或重新计算时，在会话中提出要求。
+- **查看来源**：查看报告内容附带的来源信息，核对分析依据。
+- **调整呈现**：在最新版本页面点击“编辑报告”，编辑标题、正文、指标标签和图表／表格配置，移动或删除内容，支持撤销、重做和保存。
+- **继续追问**：在支持的报告内容菜单中选择“加入提问”，将相关内容引用到输入框，补充问题后发送。
+- **查看历史**：保存编辑后可在历史侧栏查看和下载已保存的版本，历史版本只读。
+
+页面筛选不会重新计算指标卡，也不会写入保存的报告。希望保留当前筛选结果时，使用“导出当前视图”。
+
+### 5. 下载与分享
+
+报告右上角的导出菜单提供两种方式：
 
-## 语义对象引用
+| 选项 | 适合的用途 |
+| --- | --- |
+| 下载完整报告 | 下载所查看版本的完整 HTML 报告，供离线阅读 |
+| 导出当前视图 | 将当前筛选、图形和表格排序固定为 HTML，附带来源版本及导出时间，分享当前看到的内容 |
 
-在 Web 输入框输入 `@` 选择当前 Workspace 的 Marivo 对象；多词检索使用 `@"monthly revenue"`。
-选中后显示完整 `kind:path`，提交只携带精确 ref。最近七个自然日热度保存在 DSH profile；候选缓存为 30 秒。
-对象有效性由执行时 Marivo Catalog 验证，删除对象不会被相似对象自动替换。
+也可以直接让助手将报告导出为 HTML 文件。下载的文件可用浏览器打开，离线阅读和交互，无需连接原始数据源。
+编辑模式下，请先保存或取消编辑再导出。
 
+## 分析超时设置
 
-## 草稿静态预检
+在“设置 → 插件 → 插件配置 → 数据分析”中可调整 Python 分析的默认超时时间，默认为 120 秒，
+保存后对下一次分析调用生效。实际执行时限仍受 Harness 执行策略约束。
 
-在 Workspace 根目录运行 `dsh-data-analysis-presentation-lint analysis/presentation.draft.json`，
-或通过 `--project-root PATH` 显式指定 Workspace。CLI 复用 present 的草稿与 TypedDataset 校验及文件边界，
-检查草稿结构和引用的 computed JSON；不启动 Runtime、不执行分析、不生成报告文件。
-输出 JSON 的 `ok` 仅表示这些静态检查通过；`deferredChecks` 列出仍由 `marivo_present` 完成的
-Artifact 可用性与数据、codeRefs、投影后文档与渲染检查。退出码为 0（通过）、1（校验失败）、2（参数错误）。
-草稿结构通过后逐份检查 computed 文件，每份保留首个错误，修正后可再次预检。
+## 许可证
 
-int64 单元格必须是精确整数字符串，例如 `"42"`；JSON number `42` 也不接受。
-诊断保留 JSON pointer，并显示 `column query_count type=int64`、原因与修复建议。
-超过 JS 安全整数范围的 number 可能已舍入，不能转成字符串来恢复精度；应从原始精确数据重写，
-或使用绑定 Runtime 中的 `write_dataset`。预检通过不等于成功交付，仍需 present 的成功 receipt。
+本项目采用 [MIT License](LICENSE)。

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,7 +5,7 @@ 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 presentation-kit Runtime, initializes the minimal
 Workspace layout, and checks the exact interpreter, import identities, and doctor
@@ -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/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,
+        };
+    };
+}