@woosau/dsh-custom-env 0.1.8 → 0.1.10

package/README.md

@@ -28,11 +28,12 @@ dsh plugin --profile desktop remove @woosau/dsh-custom-env
 
 1. Open **Settings → Environment**
 2. Edit a row as a draft → **Confirm** to save, **Cancel** to discard
-3. Paste `NAME=VALUE` lines into the empty row to add or update several variables at once (same names overlay existing rows as drafts)
-4. Drag across rows to multi-select, or Ctrl/Cmd+click to toggle; Ctrl/Cmd+C copies selected rows as `NAME=VALUE` (input text selection still wins when present)
-5. **Restore** brings back the value from when this app session started
-6. At startup, values are injected into the Host `process.env` first; writing the user environment (registry / launchctl) is deferred off the boot path and is not broadcast. Log off or reboot before other tools need those values
-7. Use **Install** only when shown, to wire this Host’s `dsh` command into your user PATH (Windows / macOS)
+3. **Groups** (accordion) are UI/plugin labels only — they do not change `process.env` / OS sync. `.env` stays `NAME=value`; group metadata is `$DSH_HOME/.dsh-custom-env-groups.json`. Create / rename / delete groups from the headers; move a saved row with **Move to group**
+4. Paste `NAME=VALUE` lines into an empty row to add or update several variables at once (same names overlay existing rows as drafts and keep their group)
+5. Drag across rows to multi-select, or Ctrl/Cmd+click to toggle; Ctrl/Cmd+C copies selected rows as `NAME=VALUE` (input text selection still wins when present)
+6. **Restore** brings back the value from when this app session started
+7. At startup, values are injected into the Host `process.env` first; writing the user environment (registry / launchctl) is deferred via `setImmediate` into a child process and is not broadcast. Log off or reboot before other tools need those values
+8. Use **Install** only when shown, to wire this Host’s `dsh` command into your user PATH (Windows / macOS)
 
 System-reserved names (such as `PATH` and names starting with `DSH_` / `XDG_`) cannot be edited here.
 
@@ -52,25 +53,41 @@ Call the Host `customEnv` service (`ctx.get('customEnv')` or injected `ctx.custo
 ```ts
 const env = ctx.get('customEnv')
 
-await env?.setVar('MY_KEY', 'value')  // create or replace
-await env?.setVar('MY_KEY', '')       // create only if missing
+await env?.setVar('MY_KEY', 'value')              // create → default group; existing keep group
+await env?.setVar('MY_KEY', 'value', someGroupId) // also set / move group
+await env?.setVar('MY_KEY', '')                   // create only if missing
 await env?.removeVar('MY_KEY')
 
 await env?.setVars([
   { name: 'A', value: '1' },
-  { name: 'B', value: '' },           // no-op if B already exists
+  { name: 'B', value: '', group: someGroupId }, // no-op if B already exists
 ])
 await env?.removeVars(['A', 'B'])
+
+const group = await env?.createGroup('Social')
+await env?.renameGroup(group!.id, 'Social media')
+await env?.deleteGroup(group!.id, { moveToDefault: true })
+await env?.moveEntry(rowId, group!.id)
 ```
 
-Reserved names are rejected (batch calls fail entirely).
+Reserved names are rejected (batch calls fail entirely). Unknown group ids raise `custom-env/invalid-group`.
+
+| Call | Purpose |
+|------|---------|
+| `setVar(name, value, group?)` | Create/replace by name. Omit `group`: new → `default`, existing keep group. Pass `group` to assign/move |
+| `setVars([{ name, value, group? }, ...])` | Same rules per entry; last duplicate name wins |
+| `removeVar(name)` / `removeVars(names)` | Delete by name (clears membership) |
+| `createGroup(title)` | Create custom group; returns `{ id, title }` |
+| `renameGroup(id, title)` | Rename custom group (not `default`) |
+| `deleteGroup(id, { moveToDefault })` | Delete custom group; `true` moves members to default, `false` deletes their variables |
+| `moveEntry(id, groupId)` | Move one row (by Settings row id) to another group |
 
 **Settings UI — by row id**
 
 | Call | Purpose |
 |------|---------|
-| `list()` | Current variables and row ids |
-| `upsert(id, name, value)` | Create (`id` empty) or update/rename a row |
+| `list()` | Variables + `groups`; each entry has `groupId` |
+| `upsert(id, name, value, groupId?)` | Create (`id` empty; `groupId` defaults to `default`) or update/rename by id (omit `groupId` to keep group) |
 | `deleteEntry(id)` | Delete that row |
 | `restore(id)` | Restore session-start value, or remove if the row was added later |
 

package/README.zh-CN.md

@@ -28,11 +28,12 @@ dsh plugin --profile desktop remove @woosau/dsh-custom-env
 
 1. 打开 **设置 → 环境变量**
 2. 先改草稿 → **确定** 保存，**取消** 放弃
-3. 在空行粘贴多行 `NAME=VALUE` 可批量新增或覆盖同名变量（同名写入原行草稿）
-4. 拖动可多选行，Ctrl/Cmd+点击切换选中；Ctrl/Cmd+C 按 `NAME=VALUE` 复制选中行（若 Input 内有文字选区则优先复制文字）
-5. **恢复** 可回到本次应用启动时的值
-6. 启动时先注入当前 Host 的 `process.env`；写入用户环境（注册表 / launchctl）会延后到启动路径之后，且不会广播。其它工具若要读到，请注销/重启后再开终端
-7. 仅在出现 **安装** 时使用：把本 Host 的 `dsh` 接到用户 PATH（Windows / macOS）
+3. **分组**（手风琴）只是设置页/插件侧的归类，不改变 `process.env` / 操作系统同步。`.env` 仍只存 `NAME=value`；分组元数据在 `$DSH_HOME/.dsh-custom-env-groups.json`。可在标题栏新建/改名/删组；已保存行可用 **修改分组** 迁组
+4. 在空行粘贴多行 `NAME=VALUE` 可批量新增或覆盖同名变量（同名写入原行草稿，且不改其所属分组）
+5. 拖动可多选行，Ctrl/Cmd+点击切换选中；Ctrl/Cmd+C 按 `NAME=VALUE` 复制选中行（若 Input 内有文字选区则优先复制文字）
+6. **恢复** 可回到本次应用启动时的值
+7. 启动时先注入当前 Host 的 `process.env`；写入用户环境（注册表 / launchctl）会在启动路径之后的 `setImmediate` 里交给子进程，且不会广播。其它工具若要读到，请注销/重启后再开终端
+8. 仅在出现 **安装** 时使用：把本 Host 的 `dsh` 接到用户 PATH（Windows / macOS）
 
 系统保留名（如 `PATH`，以及 `DSH_` / `XDG_` 开头）不可在此编辑。
 
@@ -52,25 +53,41 @@ dsh plugin --profile desktop remove @woosau/dsh-custom-env
 ```ts
 const env = ctx.get('customEnv')
 
-await env?.setVar('MY_KEY', 'value')  // 新建或覆盖
-await env?.setVar('MY_KEY', '')       // 仅当不存在时新建
+await env?.setVar('MY_KEY', 'value')              // 新建 → 默认分组；已存在则保留原分组
+await env?.setVar('MY_KEY', 'value', someGroupId) // 同时指定/迁入分组
+await env?.setVar('MY_KEY', '')                   // 仅当不存在时新建
 await env?.removeVar('MY_KEY')
 
 await env?.setVars([
   { name: 'A', value: '1' },
-  { name: 'B', value: '' },           // B 已存在则跳过
+  { name: 'B', value: '', group: someGroupId }, // B 已存在则跳过
 ])
 await env?.removeVars(['A', 'B'])
+
+const group = await env?.createGroup('社媒')
+await env?.renameGroup(group!.id, '社交媒体')
+await env?.deleteGroup(group!.id, { moveToDefault: true })
+await env?.moveEntry(rowId, group!.id)
 ```
 
-保留名会被拒绝（批量调用整批失败）。
+保留名会被拒绝（批量调用整批失败）。未知 group id 抛出 `custom-env/invalid-group`。
+
+| 调用 | 用途 |
+|------|------|
+| `setVar(name, value, group?)` | 按名新建/覆盖。省略 `group`：新建进 `default`，已有保留分组；传入则指定/迁组 |
+| `setVars([{ name, value, group? }, ...])` | 同上；同名后者覆盖 |
+| `removeVar(name)` / `removeVars(names)` | 按名删除（并清 membership） |
+| `createGroup(title)` | 新建自定义分组，返回 `{ id, title }` |
+| `renameGroup(id, title)` | 重命名自定义分组（不可改 `default`） |
+| `deleteGroup(id, { moveToDefault })` | 删除自定义分组；`true` 成员进默认分组，`false` 连同变量删除 |
+| `moveEntry(id, groupId)` | 按设置页行 id 迁组 |
 
 **设置页：按行 id**
 
 | 调用 | 用途 |
 |------|------|
-| `list()` | 列出当前变量与行 id |
-| `upsert(id, name, value)` | 新建（`id` 为空）或更新/重命名一行 |
+| `list()` | 变量 + `groups`；每行含 `groupId` |
+| `upsert(id, name, value, groupId?)` | 新建（`id` 为空；`groupId` 默认 `default`）或按 id 更新/重命名（不传 `groupId` 则保留分组） |
 | `deleteEntry(id)` | 删除该行 |
 | `restore(id)` | 恢复启动时的值；若是启动后新增的行则删除 |