@woosau/dsh-custom-env 0.1.0 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (17) hide show
  1. package/README.md +84 -133
  2. package/README.zh-CN.md +47 -96
  3. package/lib/client.js +243 -88
  4. package/lib/index.js +312 -159
  5. package/lib/typert.host.js +171 -1
  6. package/lib/typert.remote-client.js +143 -1
  7. package/lib/types/client/format-remote-error.d.ts +10 -0
  8. package/lib/types/client/locales.d.ts +66 -8
  9. package/lib/types/env-file.d.ts +59 -11
  10. package/lib/types/index.d.ts +33 -4
  11. package/lib/types/os-user-env/index.d.ts +15 -4
  12. package/lib/types/os-user-env/macos.d.ts +15 -1
  13. package/lib/types/os-user-env/windows.d.ts +16 -1
  14. package/lib/types/types.d.ts +5 -0
  15. package/locale/en.json +1 -1
  16. package/locale/zh.json +1 -1
  17. package/package.json +2 -2
package/README.md CHANGED
@@ -1,133 +1,84 @@
1
- # dsh-custom-env
2
-
3
- English | [中文](README.zh-CN.md)
4
-
5
- Community DeepSeek Harness (DSH) plugin for managing `$DSH_HOME/.env` from **Settings → Environment**. Not an official DeepSeek AI product.
6
-
7
- On save, values are applied to the Host `process.env` immediately and synced to the **Windows / macOS** user environment (new terminals pick up OS changes after they start). Linux user-env sync is not supported.
8
-
9
- [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
10
- [![DSH plugin](https://img.shields.io/badge/DSH-plugin-0f766e.svg)](https://github.com/ownduck/dsh-custom-env)
11
-
12
- ## Features
13
-
14
- - Settings page CRUD for `$DSH_HOME/.env` (create the file if missing)
15
- - Hot-apply to the current Host process
16
- - Sync to OS user environment on Windows and macOS
17
- - Rejects bootstrap names (`PATH`, `DSH_*`, `XDG_*`, …) that app-boot will not load from `.env`
18
- - **dsh command panel**: shows the `dsh` on your user PATH vs the launcher that started this Host; when they differ, an **Install** button appears (Windows user PATH / macOS `/usr/local/bin/dsh`). No uninstall button.
19
-
20
- ## Prerequisites
21
-
22
- - A working DeepSeek Harness install with `dsh` on your PATH (CLI or Desktop-bundled CLI)
23
- - Pick a profile: `desktop` (Electron app) or `web` (browser UI). Examples below show both.
24
-
25
- ## Installation
26
-
27
- This repository ships a ready-to-run `lib/`. You do **not** need to publish to npmjs to install from GitHub.
28
-
29
- ### Desktop (recommended)
30
-
31
- Close Desktop / VertaxWork first if `plugin` fails with `EPERM` on the profile `package.json`.
32
-
33
- ```powershell
34
- dsh plugin --profile desktop add github:ownduck/dsh-custom-env
35
- ```
36
-
37
- This plugin depends on `koffi` (native). If pnpm blocks its install script, add to the profile’s `pnpm-workspace.yaml`, then re-run `add`:
38
-
39
- ```yaml
40
- allowBuilds:
41
- koffi: true
42
- ```
43
-
44
- Restart Desktop. Open **Settings → Environment**.
45
-
46
- ### Web
47
-
48
- ```powershell
49
- [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
50
- $OutputEncoding = [System.Text.Encoding]::UTF8
51
- dsh plugin --profile web add github:ownduck/dsh-custom-env
52
- dsh --profile web --dump-config
53
- ```
54
-
55
- Equivalent: `dsh plugin --profile web add https://github.com/ownduck/dsh-custom-env.git`
56
-
57
- The dump should contain a `# == dsh-custom-env` layer and a `custom-env` plugin row. Restart DSH Web and hard-refresh the browser.
58
-
59
- ### Ask an agent to install it
60
-
61
- ```text
62
- Install the DSH plugin github:ownduck/dsh-custom-env into my local desktop profile by running: dsh plugin --profile desktop add github:ownduck/dsh-custom-env. If pnpm reports ignored build scripts for koffi, add allowBuilds.koffi: true under the profile pnpm-workspace.yaml and re-run add. Then confirm Settings → Environment appears after restarting Desktop.
63
- ```
64
-
65
- ### From a local clone (`file:` / `.`)
66
-
67
- ```powershell
68
- git clone https://github.com/ownduck/dsh-custom-env.git
69
- cd dsh-custom-env
70
- dsh plugin --profile desktop add .
71
- # or: dsh plugin --profile web add .
72
- dsh --profile web --dump-config
73
- ```
74
-
75
- ### From npm (optional, after publish)
76
-
77
- ```powershell
78
- dsh plugin --profile desktop add @woosau/dsh-custom-env@latest --registry=https://registry.npmjs.org/
79
- ```
80
-
81
- ## Uninstall / reinstall
82
-
83
- ```powershell
84
- dsh plugin --profile desktop remove @woosau/dsh-custom-env
85
- dsh plugin --profile desktop add github:ownduck/dsh-custom-env
86
- ```
87
-
88
- For a `file:` / local checkout, rebuild `lib/` after source changes, then restart DSH. Re-run `plugin add` only when `package.json` or `cordis.patch.yml` changed.
89
-
90
- ## Usage
91
-
92
- 1. Open **Settings → Environment**
93
- 2. Edit as a **draft**: **Confirm** writes `$DSH_HOME/.env` (and Host/OS live); **Cancel** only reverts the input
94
- 3. After Confirm, rows show a restart tip — **new** items say “added”; **modified** items (relative to Host start) also get **Restore** (writes back the Host-start value)
95
- 4. Restart DSH / open a new terminal for the full OS effect; after Host restart, tips and Restore clear
96
- 5. In the **dsh command** block, compare PATH vs expected; click **Install** only when offered
97
-
98
- Do not store bootstrap names in `.env` (including `PATH`). Prefer ordinary names for app config. Names containing `KEY` / `SECRET` / `TOKEN` remain scrubbed from model-visible shells by existing harness policy.
99
-
100
- ### Installing the `dsh` CLI from Settings
101
-
102
- Expected path is inferred from **how this Host was started** (Desktop packaged `resources/runtime/cli/bin`, or the Node/source launcher on `argv`).
103
-
104
- | Platform | What Install does | Conflict note |
105
- | --- | --- | --- |
106
- | **Windows** | Prepends the expected bin directory to the **user** `Path` (registry). Ownership key: `Software\dsh-custom-env\Command` (not DeepSeekHarness). | Can coexist with Desktop’s PATH entry; whichever directory is first wins in new terminals. |
107
- | **macOS** | Writes symlink `/usr/local/bin/dsh` → expected launcher. Receipt: `.dsh-custom-env-command.json`. | **Same path as Desktop “Manage dsh Command…”** — installing here may replace that link. |
108
- | **Linux** | Status only; no Install button. | — |
109
-
110
- Open a **new** terminal after Install. This plugin never calls Desktop `app.relaunch`.
111
-
112
- ## Development
113
-
114
- ```powershell
115
- cd dsh-custom-env
116
- pnpm test # or: node --import tsx/esm --test tests/*.spec.ts
117
- pnpm build # rebuilds lib/ (needs sibling vertax-work esbuild for client bundle)
118
- ```
119
-
120
- Tests live under [`tests/`](tests/) (`env-file.spec.ts`, `cli-path.spec.ts`). Docs are this README pair only.
121
-
122
- ## GitHub vs npmjs
123
-
124
- | Channel | Enough for users? | Install command |
125
- | --- | --- | --- |
126
- | **GitHub only** | Yes | `dsh plugin add github:ownduck/dsh-custom-env` |
127
- | **npmjs** | Optional | `dsh plugin add @woosau/dsh-custom-env` |
128
-
129
- Pushing to GitHub is enough to share and install. Publishing to npmjs is optional convenience (shorter name, version tags, npm badges), similar to community plugins that also publish `@scope/name` on the registry.
130
-
131
- ## License
132
-
133
- MIT
1
+ # dsh-custom-env
2
+
3
+ English | [中文](README.zh-CN.md)
4
+
5
+ Community DeepSeek Harness plugin for managing environment variables in **Settings → Environment**. Not an official DeepSeek AI product.
6
+
7
+ Changes apply to the running app right away, and on Windows / macOS also to the user environment so new terminals can see them. Linux user-environment sync is not supported.
8
+
9
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
10
+
11
+ ## Install
12
+
13
+ Requires DSH with the `dsh` CLI (`desktop` or `web`).
14
+
15
+ ```powershell
16
+ dsh plugin --profile desktop add @woosau/dsh-custom-env
17
+ # or: dsh plugin --profile web add @woosau/dsh-custom-env
18
+ # or: dsh plugin --profile desktop add github:ownduck/dsh-custom-env
19
+ ```
20
+
21
+ If install fails because Desktop is locking files, quit Desktop first. After install, restart DSH and open **Settings → Environment**.
22
+
23
+ ```powershell
24
+ dsh plugin --profile desktop remove @woosau/dsh-custom-env
25
+ ```
26
+
27
+ ## For users
28
+
29
+ 1. Open **Settings → Environment**
30
+ 2. Edit a row as a draft → **Confirm** to save, **Cancel** to discard
31
+ 3. **Restore** brings back the value from when this app session started
32
+ 4. Restart the app or open a new terminal if other tools should pick up OS-level changes
33
+ 5. Use **Install** only when shown, to wire this Host’s `dsh` command into your user PATH (Windows / macOS)
34
+
35
+ System-reserved names (such as `PATH` and names starting with `DSH_` / `XDG_`) cannot be edited here.
36
+
37
+ ### When saving a value
38
+
39
+ | You save | Variable does not exist yet | Variable already exists |
40
+ |----------|-----------------------------|-------------------------|
41
+ | A non-empty value | Created | Replaced |
42
+ | An empty value | Created as empty | Left unchanged |
43
+
44
+ ## For other plugins (Remote API)
45
+
46
+ Call the Host `customEnv` service (`ctx.get('customEnv')` or injected `ctx.customEnv`).
47
+
48
+ **Everyday use — by variable name**
49
+
50
+ ```ts
51
+ const env = ctx.get('customEnv')
52
+
53
+ await env?.setVar('MY_KEY', 'value') // create or replace
54
+ await env?.setVar('MY_KEY', '') // create only if missing
55
+ await env?.removeVar('MY_KEY')
56
+
57
+ await env?.setVars([
58
+ { name: 'A', value: '1' },
59
+ { name: 'B', value: '' }, // no-op if B already exists
60
+ ])
61
+ await env?.removeVars(['A', 'B'])
62
+ ```
63
+
64
+ Reserved names are rejected (batch calls fail entirely).
65
+
66
+ **Settings UI — by row id**
67
+
68
+ | Call | Purpose |
69
+ |------|---------|
70
+ | `list()` | Current variables and row ids |
71
+ | `upsert(id, name, value)` | Create (`id` empty) or update/rename a row |
72
+ | `deleteEntry(id)` | Delete that row |
73
+ | `restore(id)` | Restore session-start value, or remove if the row was added later |
74
+
75
+ **CLI helpers**
76
+
77
+ | Call | Purpose |
78
+ |------|---------|
79
+ | `cliStatus()` | Whether this Host’s `dsh` CLI is ready / can be installed |
80
+ | `cliInstall()` | Install or repair that CLI entry |
81
+
82
+ ## License
83
+
84
+ MIT
package/README.zh-CN.md CHANGED
@@ -2,131 +2,82 @@
2
2
 
3
3
  [English](README.md) | 中文
4
4
 
5
- 社区维护的 DeepSeek Harness（DSH）插件：在 **设置 → 环境变量** 中管理 `$DSH_HOME/.env`。非 DeepSeek AI 官方产品。
5
+ 社区 DeepSeek Harness 插件：在 **设置 → 环境变量** 里管理环境变量。非 DeepSeek AI 官方产品。
6
6
 
7
- 保存后立即写入 Host 的 `process.env`，并在 **Windows / macOS** 同步到用户环境（新开终端才能看到 OS 侧变更）。不同步 Linux 用户环境。
7
+ 保存后立即作用于当前应用；在 Windows / macOS 上还会写入用户环境，方便新开的终端读到。不支持同步 Linux 用户环境。
8
8
 
9
9
  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
10
- [![DSH plugin](https://img.shields.io/badge/DSH-plugin-0f766e.svg)](https://github.com/ownduck/dsh-custom-env)
11
-
12
- ## 功能
13
-
14
- - 设置页对 `$DSH_HOME/.env` 增删改（文件不存在时自动创建）
15
- - 热写到当前 Host 进程
16
- - Windows / macOS 用户环境同步
17
- - 拒绝 bootstrap 名（`PATH`、`DSH_*`、`XDG_*` 等），与 app-boot 对 `.env` 的限制一致
18
- - **dsh 命令**区块：展示用户 PATH 上的 `dsh` 与启动本 Host 的期望启动器；不一致时显示 **安装** 按钮（Windows 用户 PATH / macOS `/usr/local/bin/dsh`）。无卸载按钮。
19
-
20
- ## 前置条件
21
-
22
- - 已安装可用的 DeepSeek Harness，且终端里能运行 `dsh`（CLI 或 Desktop 自带 CLI）
23
- - 选择 profile：`desktop`（Electron）或 `web`（浏览器）。下文两种都有。
24
10
 
25
11
  ## 安装
26
12
 
27
- 本仓库已包含可运行的 `lib/`。**不发 npmjs 也能从 GitHub 安装。**
28
-
29
- ### Desktop（推荐）
30
-
31
- 若 `plugin` 报 profile `package.json` 的 `EPERM`，先退出 Desktop / VertaxWork。
32
-
33
- ```powershell
34
- dsh plugin --profile desktop add github:ownduck/dsh-custom-env
35
- ```
36
-
37
- 本插件依赖原生包 `koffi`。若 pnpm 拦截其 install 脚本，在该 profile 的 `pnpm-workspace.yaml` 中加入后重新 `add`：
38
-
39
- ```yaml
40
- allowBuilds:
41
- koffi: true
42
- ```
43
-
44
- 重启 Desktop，打开 **设置 → 环境变量**。
45
-
46
- ### Web
47
-
48
- ```powershell
49
- [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
50
- $OutputEncoding = [System.Text.Encoding]::UTF8
51
- dsh plugin --profile web add github:ownduck/dsh-custom-env
52
- dsh --profile web --dump-config
53
- ```
54
-
55
- 等价：`dsh plugin --profile web add https://github.com/ownduck/dsh-custom-env.git`
56
-
57
- 配置输出中应出现 `# == dsh-custom-env` 层和 `custom-env` 插件行。然后重启 DSH Web，并在浏览器硬刷新。
58
-
59
- ### 让 Agent 帮你安装
60
-
61
- ```text
62
- 请将 DSH 插件 github:ownduck/dsh-custom-env 安装到本机 desktop profile，执行：dsh plugin --profile desktop add github:ownduck/dsh-custom-env。若 pnpm 提示忽略 koffi 的 build scripts，在该 profile 的 pnpm-workspace.yaml 中加入 allowBuilds.koffi: true 后重新 add。重启 Desktop 后确认「设置 → 环境变量」可用。
63
- ```
64
-
65
- ### 从本地克隆安装（`file:` / `.`）
66
-
67
- ```powershell
68
- git clone https://github.com/ownduck/dsh-custom-env.git
69
- cd dsh-custom-env
70
- dsh plugin --profile desktop add .
71
- # 或：dsh plugin --profile web add .
72
- dsh --profile web --dump-config
73
- ```
74
-
75
- ### 从 npm 安装（可选，发布后）
13
+ 需已安装 DSH，并能使用 `dsh` 命令（`desktop` 或 `web`）。
76
14
 
77
15
  ```powershell
78
- dsh plugin --profile desktop add @woosau/dsh-custom-env@latest --registry=https://registry.npmjs.org/
16
+ dsh plugin --profile desktop add @woosau/dsh-custom-env
17
+ # 或: dsh plugin --profile web add @woosau/dsh-custom-env
18
+ # 或: dsh plugin --profile desktop add github:ownduck/dsh-custom-env
79
19
  ```
80
20
 
81
- ## 卸载 / 重装
21
+ 若因 Desktop 占用文件导致安装失败，先退出 Desktop。安装后重启 DSH，打开 **设置 → 环境变量**。
82
22
 
83
23
  ```powershell
84
24
  dsh plugin --profile desktop remove @woosau/dsh-custom-env
85
- dsh plugin --profile desktop add github:ownduck/dsh-custom-env
86
25
  ```
87
26
 
88
- 本地 `file:` 开发：改 `src` 后重建 `lib/`，再重启 DSH。只有改了 `package.json` / `cordis.patch.yml` 才需要重新 `plugin add`。
89
-
90
- ## 使用
27
+ ## 给使用者
91
28
 
92
29
  1. 打开 **设置 → 环境变量**
93
- 2. **草稿编辑**：点 **确定** 才写入 `$DSH_HOME/.env`（并热写 Host/OS）；**取消** 只恢复输入框
94
- 3. 确定后行旁提示需重启——**新增**标为新增项；相对 Host 启动值的 **修改** 另有 **恢复**（写回启动时的值）
95
- 4. 完整生效请重启 DSH / 新开终端；Host 重启后提示与恢复按钮消失
96
- 5. 在 **dsh 命令**区块对比 PATH 与期望路径；仅在出现按钮时点击 **安装**
30
+ 2. 先改草稿 → **确定** 保存，**取消** 放弃
31
+ 3. **恢复** 可回到本次应用启动时的值
32
+ 4. 若希望其他工具也读到系统侧变更，请重启应用或新开终端
33
+ 5. 仅在出现 **安装** 时使用：把本 Host 的 `dsh` 接到用户 PATH（Windows / macOS）
97
34
 
98
- 不要把 bootstrap 名（含 `PATH`）写进 `.env`。应用配置用普通名字即可。名称含 `KEY` / `SECRET` / `TOKEN` 时仍会被现有 harness 策略从模型可见 shell 中 scrub。
35
+ 系统保留名（如 `PATH`，以及 `DSH_` / `XDG_` 开头）不可在此编辑。
99
36
 
100
- ### 在设置页安装 `dsh` CLI
37
+ ### 保存时怎么处理
101
38
 
102
- 期望路径由 **当前 Host 的启动方式** 推断（Desktop 打包的 `resources/runtime/cli/bin`，或 Node/源码启动的 `argv` 启动器）。
39
+ | 你保存的内容 | 变量还不存在 | 变量已存在 |
40
+ |--------------|--------------|------------|
41
+ | 非空 | 新建 | 覆盖 |
42
+ | 空 | 建为空变量 | 保持原样不动 |
103
43
 
104
- | 平台 | 安装行为 | 冲突说明 |
105
- | --- | --- | --- |
106
- | **Windows** | 将期望 bin 目录写入用户 `Path`（注册表）。所有权键：`Software\dsh-custom-env\Command`（不用 DeepSeekHarness）。 | 可与 Desktop 的 PATH 条目并存；新终端里谁排前用谁。 |
107
- | **macOS** | 写符号链接 `/usr/local/bin/dsh` → 期望启动器。收据：`.dsh-custom-env-command.json`。 | **与 Desktop「管理 dsh 命令…」同一路径**，可能覆盖其链接。 |
108
- | **Linux** | 仅展示状态，无安装按钮。 | — |
44
+ ## 给其他插件（Remote API）
109
45
 
110
- 安装后请 **新开** 终端。本插件不会调用 Desktop `app.relaunch`。
46
+ 通过 Host 的 `customEnv` 服务调用（`ctx.get('customEnv')` 或已注入的 `ctx.customEnv`）。
111
47
 
112
- ## 开发
48
+ **常用：按变量名**
113
49
 
114
- ```powershell
115
- cd dsh-custom-env
116
- pnpm test # 或：node --import tsx/esm --test tests/*.spec.ts
117
- pnpm build # 重建 lib/（client 打包依赖旁路的 vertax-work esbuild）
50
+ ```ts
51
+ const env = ctx.get('customEnv')
52
+
53
+ await env?.setVar('MY_KEY', 'value') // 新建或覆盖
54
+ await env?.setVar('MY_KEY', '') // 仅当不存在时新建
55
+ await env?.removeVar('MY_KEY')
56
+
57
+ await env?.setVars([
58
+ { name: 'A', value: '1' },
59
+ { name: 'B', value: '' }, // B 已存在则跳过
60
+ ])
61
+ await env?.removeVars(['A', 'B'])
118
62
  ```
119
63
 
120
- 测试在 [`tests/`](tests/)（`env-file.spec.ts`、`cli-path.spec.ts`）。文档即本 README 中英双语。
64
+ 保留名会被拒绝（批量调用整批失败）。
65
+
66
+ **设置页：按行 id**
121
67
 
122
- ## GitHub 与 npmjs
68
+ | 调用 | 用途 |
69
+ |------|------|
70
+ | `list()` | 列出当前变量与行 id |
71
+ | `upsert(id, name, value)` | 新建（`id` 为空）或更新/重命名一行 |
72
+ | `deleteEntry(id)` | 删除该行 |
73
+ | `restore(id)` | 恢复启动时的值；若是启动后新增的行则删除 |
123
74
 
124
- | 渠道 | 够不够用 | 安装命令 |
125
- | --- | --- | --- |
126
- | **只推 GitHub** | 够 | `dsh plugin add github:ownduck/dsh-custom-env` |
127
- | **再发 npmjs** | 可选 | `dsh plugin add @woosau/dsh-custom-env` |
75
+ **CLI**
128
76
 
129
- 推到 GitHub 即可分享与安装。发 npmjs 只是可选便利（短包名、版本号、徽章），与社区插件同时维护 GitHub + npm 的做法类似。
77
+ | 调用 | 用途 |
78
+ |------|------|
79
+ | `cliStatus()` | 本 Host 的 `dsh` 是否可用 / 能否安装 |
80
+ | `cliInstall()` | 安装或修复该 CLI 入口 |
130
81
 
131
82
  ## 许可证
132
83