@woosau/dsh-custom-env 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ownduck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,133 @@
-# Temporary Holding Version
+# dsh-custom-env
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+English | [中文](README.zh-CN.md)
+
+Community DeepSeek Harness (DSH) plugin for managing `$DSH_HOME/.env` from **Settings → Environment**. Not an official DeepSeek AI product.
+
+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.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![DSH plugin](https://img.shields.io/badge/DSH-plugin-0f766e.svg)](https://github.com/ownduck/dsh-custom-env)
+
+## Features
+
+- Settings page CRUD for `$DSH_HOME/.env` (create the file if missing)
+- Hot-apply to the current Host process
+- Sync to OS user environment on Windows and macOS
+- Rejects bootstrap names (`PATH`, `DSH_*`, `XDG_*`, …) that app-boot will not load from `.env`
+- **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.
+
+## Prerequisites
+
+- A working DeepSeek Harness install with `dsh` on your PATH (CLI or Desktop-bundled CLI)
+- Pick a profile: `desktop` (Electron app) or `web` (browser UI). Examples below show both.
+
+## Installation
+
+This repository ships a ready-to-run `lib/`. You do **not** need to publish to npmjs to install from GitHub.
+
+### Desktop (recommended)
+
+Close Desktop / VertaxWork first if `plugin` fails with `EPERM` on the profile `package.json`.
+
+```powershell
+dsh plugin --profile desktop add github:ownduck/dsh-custom-env
+```
+
+This plugin depends on `koffi` (native). If pnpm blocks its install script, add to the profile’s `pnpm-workspace.yaml`, then re-run `add`:
+
+```yaml
+allowBuilds:
+  koffi: true
+```
+
+Restart Desktop. Open **Settings → Environment**.
+
+### Web
+
+```powershell
+[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+$OutputEncoding = [System.Text.Encoding]::UTF8
+dsh plugin --profile web add github:ownduck/dsh-custom-env
+dsh --profile web --dump-config
+```
+
+Equivalent: `dsh plugin --profile web add https://github.com/ownduck/dsh-custom-env.git`
+
+The dump should contain a `# == dsh-custom-env` layer and a `custom-env` plugin row. Restart DSH Web and hard-refresh the browser.
+
+### Ask an agent to install it
+
+```text
+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.
+```
+
+### From a local clone (`file:` / `.`)
+
+```powershell
+git clone https://github.com/ownduck/dsh-custom-env.git
+cd dsh-custom-env
+dsh plugin --profile desktop add .
+# or: dsh plugin --profile web add .
+dsh --profile web --dump-config
+```
+
+### From npm (optional, after publish)
+
+```powershell
+dsh plugin --profile desktop add @woosau/dsh-custom-env@latest --registry=https://registry.npmjs.org/
+```
+
+## Uninstall / reinstall
+
+```powershell
+dsh plugin --profile desktop remove @woosau/dsh-custom-env
+dsh plugin --profile desktop add github:ownduck/dsh-custom-env
+```
+
+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.
+
+## Usage
+
+1. Open **Settings → Environment**
+2. Edit as a **draft**: **Confirm** writes `$DSH_HOME/.env` (and Host/OS live); **Cancel** only reverts the input
+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)
+4. Restart DSH / open a new terminal for the full OS effect; after Host restart, tips and Restore clear
+5. In the **dsh command** block, compare PATH vs expected; click **Install** only when offered
+
+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.
+
+### Installing the `dsh` CLI from Settings
+
+Expected path is inferred from **how this Host was started** (Desktop packaged `resources/runtime/cli/bin`, or the Node/source launcher on `argv`).
+
+| Platform | What Install does | Conflict note |
+| --- | --- | --- |
+| **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. |
+| **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. |
+| **Linux** | Status only; no Install button. | — |
+
+Open a **new** terminal after Install. This plugin never calls Desktop `app.relaunch`.
+
+## Development
+
+```powershell
+cd dsh-custom-env
+pnpm test   # or: node --import tsx/esm --test tests/*.spec.ts
+pnpm build  # rebuilds lib/ (needs sibling vertax-work esbuild for client bundle)
+```
+
+Tests live under [`tests/`](tests/) (`env-file.spec.ts`, `cli-path.spec.ts`). Docs are this README pair only.
+
+## GitHub vs npmjs
+
+| Channel | Enough for users? | Install command |
+| --- | --- | --- |
+| **GitHub only** | Yes | `dsh plugin add github:ownduck/dsh-custom-env` |
+| **npmjs** | Optional | `dsh plugin add @woosau/dsh-custom-env` |
+
+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.
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,133 @@
+# dsh-custom-env
+
+[English](README.md) | 中文
+
+社区维护的 DeepSeek Harness（DSH）插件：在 **设置 → 环境变量** 中管理 `$DSH_HOME/.env`。非 DeepSeek AI 官方产品。
+
+保存后立即写入 Host 的 `process.env`，并在 **Windows / macOS** 同步到用户环境（新开终端才能看到 OS 侧变更）。不同步 Linux 用户环境。
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![DSH plugin](https://img.shields.io/badge/DSH-plugin-0f766e.svg)](https://github.com/ownduck/dsh-custom-env)
+
+## 功能
+
+- 设置页对 `$DSH_HOME/.env` 增删改（文件不存在时自动创建）
+- 热写到当前 Host 进程
+- Windows / macOS 用户环境同步
+- 拒绝 bootstrap 名（`PATH`、`DSH_*`、`XDG_*` 等），与 app-boot 对 `.env` 的限制一致
+- **dsh 命令**区块：展示用户 PATH 上的 `dsh` 与启动本 Host 的期望启动器；不一致时显示 **安装** 按钮（Windows 用户 PATH / macOS `/usr/local/bin/dsh`）。无卸载按钮。
+
+## 前置条件
+
+- 已安装可用的 DeepSeek Harness，且终端里能运行 `dsh`（CLI 或 Desktop 自带 CLI）
+- 选择 profile：`desktop`（Electron）或 `web`（浏览器）。下文两种都有。
+
+## 安装
+
+本仓库已包含可运行的 `lib/`。**不发 npmjs 也能从 GitHub 安装。**
+
+### Desktop（推荐）
+
+若 `plugin` 报 profile `package.json` 的 `EPERM`，先退出 Desktop / VertaxWork。
+
+```powershell
+dsh plugin --profile desktop add github:ownduck/dsh-custom-env
+```
+
+本插件依赖原生包 `koffi`。若 pnpm 拦截其 install 脚本，在该 profile 的 `pnpm-workspace.yaml` 中加入后重新 `add`：
+
+```yaml
+allowBuilds:
+  koffi: true
+```
+
+重启 Desktop，打开 **设置 → 环境变量**。
+
+### Web
+
+```powershell
+[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+$OutputEncoding = [System.Text.Encoding]::UTF8
+dsh plugin --profile web add github:ownduck/dsh-custom-env
+dsh --profile web --dump-config
+```
+
+等价：`dsh plugin --profile web add https://github.com/ownduck/dsh-custom-env.git`
+
+配置输出中应出现 `# == dsh-custom-env` 层和 `custom-env` 插件行。然后重启 DSH Web，并在浏览器硬刷新。
+
+### 让 Agent 帮你安装
+
+```text
+请将 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 后确认「设置 → 环境变量」可用。
+```
+
+### 从本地克隆安装（`file:` / `.`）
+
+```powershell
+git clone https://github.com/ownduck/dsh-custom-env.git
+cd dsh-custom-env
+dsh plugin --profile desktop add .
+# 或：dsh plugin --profile web add .
+dsh --profile web --dump-config
+```
+
+### 从 npm 安装（可选，发布后）
+
+```powershell
+dsh plugin --profile desktop add @woosau/dsh-custom-env@latest --registry=https://registry.npmjs.org/
+```
+
+## 卸载 / 重装
+
+```powershell
+dsh plugin --profile desktop remove @woosau/dsh-custom-env
+dsh plugin --profile desktop add github:ownduck/dsh-custom-env
+```
+
+本地 `file:` 开发：改 `src` 后重建 `lib/`，再重启 DSH。只有改了 `package.json` / `cordis.patch.yml` 才需要重新 `plugin add`。
+
+## 使用
+
+1. 打开 **设置 → 环境变量**
+2. **草稿编辑**：点 **确定** 才写入 `$DSH_HOME/.env`（并热写 Host/OS）；**取消** 只恢复输入框
+3. 确定后行旁提示需重启——**新增**标为新增项；相对 Host 启动值的 **修改** 另有 **恢复**（写回启动时的值）
+4. 完整生效请重启 DSH / 新开终端；Host 重启后提示与恢复按钮消失
+5. 在 **dsh 命令**区块对比 PATH 与期望路径；仅在出现按钮时点击 **安装**
+
+不要把 bootstrap 名（含 `PATH`）写进 `.env`。应用配置用普通名字即可。名称含 `KEY` / `SECRET` / `TOKEN` 时仍会被现有 harness 策略从模型可见 shell 中 scrub。
+
+### 在设置页安装 `dsh` CLI
+
+期望路径由 **当前 Host 的启动方式** 推断（Desktop 打包的 `resources/runtime/cli/bin`，或 Node/源码启动的 `argv` 启动器）。
+
+| 平台 | 安装行为 | 冲突说明 |
+| --- | --- | --- |
+| **Windows** | 将期望 bin 目录写入用户 `Path`（注册表）。所有权键：`Software\dsh-custom-env\Command`（不用 DeepSeekHarness）。 | 可与 Desktop 的 PATH 条目并存；新终端里谁排前用谁。 |
+| **macOS** | 写符号链接 `/usr/local/bin/dsh` → 期望启动器。收据：`.dsh-custom-env-command.json`。 | **与 Desktop「管理 dsh 命令…」同一路径**，可能覆盖其链接。 |
+| **Linux** | 仅展示状态，无安装按钮。 | — |
+
+安装后请 **新开** 终端。本插件不会调用 Desktop `app.relaunch`。
+
+## 开发
+
+```powershell
+cd dsh-custom-env
+pnpm test   # 或：node --import tsx/esm --test tests/*.spec.ts
+pnpm build  # 重建 lib/（client 打包依赖旁路的 vertax-work esbuild）
+```
+
+测试在 [`tests/`](tests/)（`env-file.spec.ts`、`cli-path.spec.ts`）。文档即本 README 中英双语。
+
+## GitHub 与 npmjs
+
+| 渠道 | 够不够用 | 安装命令 |
+| --- | --- | --- |
+| **只推 GitHub** | 够 | `dsh plugin add github:ownduck/dsh-custom-env` |
+| **再发 npmjs** | 可选 | `dsh plugin add @woosau/dsh-custom-env` |
+
+推到 GitHub 即可分享与安装。发 npmjs 只是可选便利（短包名、版本号、徽章），与社区插件同时维护 GitHub + npm 的做法类似。
+
+## 许可证
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: custom-env
+      name: '@woosau/dsh-custom-env'