dsh-quick-actions 0.1.0 → 0.2.0-rc.1

package/README.en.md

@@ -20,29 +20,33 @@ This release has **no insert action** (insert at the selection, keep the editing
 
 | Item | Value |
 |---|---|
-| Verified baseline | DSH core packages at `0.1.5-rc.1`. Note that `dsh --version` on the desktop build prints its dependency-set label, a different number from the core package version |
-| DSH peers | `>=0.1.5-rc.1` |
-| Cordis | `^4.0.2` |
-| Schemastery | `^3.18.2` |
+| Verified baseline | DSH core packages at `0.1.7-rc.1`. Note that `dsh --version` on the desktop build prints its dependency-set label, a different number from the core package version |
+| DSH peers | `>=0.1.7-alpha.2` |
+| Cordis | `^4.0.4` |
+| Schemastery | `^3.18.4` |
 | React and React DOM (browser side) | `^18.3.1`, supplied by the web shell's module table rather than installed into the profile |
-| DSH UI primitives (browser side) | `>=0.1.5-rc.1`, also supplied by the module table |
+| DSH UI primitives (browser side) | `>=0.1.7-alpha.2`, also supplied by the module table |
 | Platform | `web` profile only |
 
 Nothing is capability-detected at install or at runtime, so there is no feature tiering that varies with the DSH version: either the whole plugin installs and runs, or it does not.
 
-The floor is the DSH release whose Input contract this plugin reads. **Do not run it against anything older**: `0.1.5-rc.1` renamed `imageIds` to `attachmentIds` in the published snapshot, and this plugin reads the new name.
+The floor is the DSH release whose Settings form this plugin reads. **Do not run it against anything older**: `0.1.7-alpha.1` rewrote Settings — plugins no longer register namespaces of their own, and user data became the plugin's own Config, written into the profile. This release reads and writes the new model only, and on the `0.1.5` and `0.1.6` lines its Client never starts. For those lines, install this plugin's `0.1.0`.
+
+The verified baseline sits one release above the floor: this release is verified on `0.1.7-rc.1`, and nothing this plugin consumes changed between `0.1.7-alpha.2` and `0.1.7-rc.1`, so the floor stays at `0.1.7-alpha.2` and users still on the alpha channel can install it.
 
 No upper bound is declared, but **that is not a promise of forward compatibility**. Two things to know:
 
-- **The rc line does break published contracts.** Between `0.1.2-rc.1` and `0.1.5-rc.1`, the very field this plugin uses as its only send precondition was renamed, and the whole Quick Actions area rendered an error boundary after the upgrade. Every DSH upgrade may need a follow-up release of this plugin; if the area shows an error after one, suspect another contract change and please open an issue.
-- **`>=0.1.5-rc.1` does not match the next prerelease under semver.** A prerelease version only satisfies a comparator with the same major.minor.patch, so `0.1.6-rc.1` does not satisfy `>=0.1.5-rc.1` — and every DSH version published so far is a prerelease. The moment DSH ships a new rc, package managers report an unmet peer dependency even when the plugin is fine. That is semver's rule for prereleases rather than this plugin being picky: if `dsh plugin add` installs it, keep using it, and judge breakage by the point above. (The `Issues with peer dependencies found` note under "What a good install looks like" below has a different cause; the two show up together.)
+- **The prerelease lines do break published contracts.** Between `0.1.2-rc.1` and `0.1.5-rc.1`, the very field this plugin uses as its only send precondition was renamed; `0.1.7-alpha.1` then replaced the Settings interface wholesale, and an older release of this plugin fails to activate its Host on it (`settings.register is not a function`). Every DSH upgrade may need a follow-up release of this plugin; if the Quick Actions break after one, suspect another contract change and please open an issue.
+- **`>=0.1.7-alpha.2` does not match the next prerelease under semver.** A prerelease version only satisfies a comparator with the same major.minor.patch, so `0.1.8-rc.1` does not satisfy `>=0.1.7-alpha.2` — and every DSH version published so far is a prerelease. The moment DSH ships a new prerelease, package managers report an unmet peer dependency even when the plugin is fine; conversely, semver does not stop you installing this release onto the `0.1.5` line either. That is semver's rule for prereleases rather than this plugin being picky: if `dsh plugin add` installs it, keep using it, and judge breakage by the point above. (The `Issues with peer dependencies found` note under "What a good install looks like" below has a different cause; the two show up together.)
 
 ## Install
 
 ```sh
-dsh plugin --profile web add dsh-quick-actions
+dsh plugin --profile web add dsh-quick-actions@next
 ```
 
+**Keep the `@next`.** DSH's own npm `latest` still points at the `0.1.5` line, so this release is published under the `next` dist-tag. Without the tag you get `0.1.0` from `latest`, which supports only the `0.1.5` and `0.1.6` lines and fails to activate on `0.1.7`. Once DSH moves `0.1.7` to `latest`, this plugin moves back to `latest` with it.
+
 Then restart the web profile. One package is the whole thing: it carries `dsh.bundle.patch`, which inserts its Host half into the profile, while its `dsh.client` declaration makes the web app load the browser half.
 
 ### Local / offline install
@@ -50,7 +54,7 @@ Then restart the web profile. One package is the whole thing: it carries `dsh.bu
 ```sh
 mkdir -p /tmp/quick-actions
 pnpm --filter dsh-quick-actions pack --pack-destination /tmp/quick-actions
-dsh plugin --profile web add /tmp/quick-actions/dsh-quick-actions-0.1.0.tgz
+dsh plugin --profile web add /tmp/quick-actions/dsh-quick-actions-0.2.0-rc.1.tgz
 ```
 
 The `--filter` form works from anywhere in the repository; from the package directory itself, `pnpm pack --pack-destination /tmp/quick-actions` is the same thing.
@@ -118,6 +122,7 @@ Field rules:
 - `id` is required, unique across the catalog and **permanent**. Label, icon and text may change under the same `id`; `confirm` is part of the safety signature, so changing it needs a new `id` — and so does making the text start with `/`, or stop starting with it.
 - `label` and `text` are required; `icon` and `confirm` are optional, and `confirm` defaults to `true`.
 - An invalid preset (a missing field, a duplicate `id`, a catalog over 50 entries) makes **plugin loading fail loudly** and lists every problem at once, rather than truncating silently.
+- `presets` sits under the same row's `config` as your action data (see "Settings paths" below), and this plugin never writes it. It is a DSH volatile field: editing it while the profile runs reaches the Quick Actions immediately; an invalid catalog written that way shows a catalog error in the Quick Actions area, and the next profile restart fails plugin loading with the list of problems.
 
 Users can hide or clone a preset but never edit or delete it; a clone becomes an ordinary Custom Quick Action.
 
@@ -145,13 +150,31 @@ Static text whose first non-whitespace character is `/` is marked as a command.
 
 ## Settings paths
 
-User data lives in `<DSH_HOME>/settings.yaml` (`~/.dsh` when `DSH_HOME` is unset):
+User data is the plugin's own Config, on its loader entry `composer-quick-actions`. DSH Settings writes it into the **active profile**'s `<DSH_HOME>/profiles/web/cordis.patch.yml` (`~/.dsh` when `DSH_HOME` is unset), under that id's row `config`:
+
+```yaml
+- id: composer-quick-actions
+  name: dsh-quick-actions
+  config:
+    schemaVersion: 1
+    layout: bar
+    userActionsById: { ... }
+    actionOrder: [ ... ]
+    presetStateById: { ... }
+```
 
-- `composer-quick-actions` — the **only** persisted namespace: layout, custom actions, the shared order and preset differences.
-- `composer-quick-actions-catalog` — the preset catalog. Read-only, never written to the user layer, so it does **not** appear in that file.
+- Those five fields hold the layout, custom actions, the shared order and preset differences — the **only** persisted data. The same row's `config.presets` is the presets you declared, and this plugin never writes it.
+- Each profile keeps its own copy. The row may not exist at all until your first change in the management panel, and DSH removes it again once everything is back to its defaults.
+- The plugin ships its own management panel, so it opts out of the Settings page DSH would otherwise generate for it.
 
 The Host is the single validation authority and normalizes stored data idempotently at boot. Every change made in the UI carries an expected revision; on a conflict the panel refreshes to the latest state and asks you to confirm again, never silently overwriting someone else's write. Data written by a higher `schemaVersion` is kept as-is, so a downgrade round-trip loses nothing.
 
+### Migrating from DSH 0.1.5 / 0.1.6
+
+Older releases kept the data in the `composer-quick-actions` section of `<DSH_HOME>/settings.yaml`. On its first boot, once every plugin has settled, DSH `0.1.7` renames the whole file to `settings.yaml.imported` and imports each section into the plugin entry of the same id — **exactly once**, and only for whichever profile boots first.
+
+For that import to land, this release of the plugin must be the one running at that moment. **Upgrade this plugin first, then DSH** (or both within the same restart). If DSH was upgraded first, the old plugin fails to activate on it, the import fails with it, and the data stays untouched in `settings.yaml.imported`. Migrate by hand then: copy the five fields under that section verbatim under the row's `config` shown above, and restart the profile.
+
 ## Upgrade, downgrade and uninstall
 
 **Upgrade / downgrade**:
@@ -170,13 +193,13 @@ Cross-version data compatibility is the Host's job: new presets are appended to
 dsh plugin --profile web remove dsh-quick-actions
 ```
 
-Both the dependency and the layer in `dsh.profile.bundles` go away. After a profile restart the actions are gone.
+Both the dependency and the layer in `dsh.profile.bundles` go away. After a profile restart the actions are gone. The `id: composer-quick-actions` row in `cordis.patch.yml` stays as it is — your actions live in its `config`, and a reinstall picks the row back up by id, so they come back. If you uninstall without reinstalling, the profile logs a `patch: entry "composer-quick-actions" not found` warning for that row on every start; it does not block startup, and step 1 below removes it.
 
 **Full manual cleanup** (uninstalling does none of this, because a reinstall should restore your actions):
 
-1. Delete the `composer-quick-actions` section from `<DSH_HOME>/settings.yaml` — the only place user data lives.
-2. Remove any entry you added for this plugin from `<DSH_HOME>/profiles/web/pnpm-workspace.yaml`.
-3. Delete any `config` you wrote for `composer-quick-actions` in the profile's `cordis.patch.yml`.
+1. Delete the `id: composer-quick-actions` row from `<DSH_HOME>/profiles/web/cordis.patch.yml` — the only place user data (and the presets you declared) lives.
+2. If a `composer-quick-actions` section is still left in `<DSH_HOME>/settings.yaml.imported`, delete it too.
+3. Remove any entry you added for this plugin from `<DSH_HOME>/profiles/web/pnpm-workspace.yaml`.
 4. Restart the profile.
 
 ## Development

package/README.md

@@ -20,29 +20,33 @@
 
 | 项目 | 值 |
 |---|---|
-| 验证基线 | DSH 核心包 `0.1.5-rc.1`。桌面端 `dsh --version` 打印的是依赖集标签，与核心包版本不是同一个数字 |
-| DSH peer | `>=0.1.5-rc.1` |
-| Cordis | `^4.0.2` |
-| Schemastery | `^3.18.2` |
+| 验证基线 | DSH 核心包 `0.1.7-rc.1`。桌面端 `dsh --version` 打印的是依赖集标签，与核心包版本不是同一个数字 |
+| DSH peer | `>=0.1.7-alpha.2` |
+| Cordis | `^4.0.4` |
+| Schemastery | `^3.18.4` |
 | React 与 React DOM（浏览器侧） | `^18.3.1`，由 web shell 的模块表提供，不从 profile 安装 |
-| DSH UI primitives（浏览器侧） | `>=0.1.5-rc.1`，同样由模块表提供 |
+| DSH UI primitives（浏览器侧） | `>=0.1.7-alpha.2`，同样由模块表提供 |
 | 平台 | 只支持 `web` profile |
 
 安装与运行都不检测 DSH 能力，因此不存在随版本变化的功能分档：要么整个插件能装能跑，要么装不上。
 
-下界取的是本插件读取其 Input 契约的那个 DSH 版本。**不要在更低版本上使用**：`0.1.5-rc.1` 把公开快照里的 `imageIds` 改名为 `attachmentIds`，本插件按新名读取。
+下界取的是本插件读取其 Settings 表单的那个 DSH 版本。**不要在更低版本上使用**：`0.1.7-alpha.1` 重写了 Settings——插件不再自己注册命名空间，用户数据改为插件自己的 Config、写进 profile。本版只按新模型读写，在 `0.1.5`、`0.1.6` 线上 Client 根本不会启动。要在那两条线上用，请装本插件的 `0.1.0`。
+
+验证基线比下界高一版：本版在 `0.1.7-rc.1` 上验证，而 `0.1.7-alpha.2` 到 `0.1.7-rc.1` 之间，本插件用到的契约逐字未变，所以下界仍停在 `0.1.7-alpha.2`，留在 alpha 通道的用户照样能装。
 
 上界不设，但**这不等于向后兼容有保障**，两点需要知道：
 
-- **rc 阶段会破坏公开契约。** `0.1.2-rc.1` 到 `0.1.5-rc.1` 之间，被本插件用作唯一发送判据的那个字段就被改了名，升级 DSH 后整个快捷动作区域会显示错误边界。每次 DSH 升级都可能需要本插件跟一版；升级后若该区域出错，多半又是契约变更，请提 issue。
-- **`>=0.1.5-rc.1` 在 semver 里匹配不到下一个预发布版本。** 预发布版本只满足「主次修订号完全相同」的比较符，因此 `0.1.6-rc.1` 不满足 `>=0.1.5-rc.1`；而 DSH 至今发布的每个版本都是预发布。DSH 一旦发出新的 rc，包管理器就会报未满足的 peer 依赖，即使插件本身没问题。这是 semver 对预发布的规定，不是本插件挑版本——`dsh plugin add` 装得上就可以继续用，出错时按上一条判断。（下面「装好之后」里那条 `Issues with peer dependencies found` 说的是另一个原因，两者会一起出现。）
+- **预发布阶段会破坏公开契约。** `0.1.2-rc.1` 到 `0.1.5-rc.1` 之间，被本插件用作唯一发送判据的那个字段被改了名；`0.1.7-alpha.1` 又整个换掉了 Settings 接口，旧版本插件在它上面 Host 直接激活失败（`settings.register is not a function`）。每次 DSH 升级都可能需要本插件跟一版；升级后若快捷动作出错，多半又是契约变更，请提 issue。
+- **`>=0.1.7-alpha.2` 在 semver 里匹配不到下一个预发布版本。** 预发布版本只满足「主次修订号完全相同」的比较符，因此 `0.1.8-rc.1` 不满足 `>=0.1.7-alpha.2`；而 DSH 至今发布的每个版本都是预发布。DSH 一旦发出新的预发布，包管理器就会报未满足的 peer 依赖，即使插件本身没问题。反过来，semver 也拦不住你把本版装到 `0.1.5` 线上。这是 semver 对预发布的规定，不是本插件挑版本——`dsh plugin add` 装得上就可以继续用，出错时按上一条判断。（下面「装好之后」里那条 `Issues with peer dependencies found` 说的是另一个原因，两者会一起出现。）
 
 ## 安装
 
 ```sh
-dsh plugin --profile web add dsh-quick-actions
+dsh plugin --profile web add dsh-quick-actions@next
 ```
 
+**`@next` 不能省。** DSH 自己的 npm `latest` 还停在 `0.1.5` 线，所以本版发在 `next` dist-tag 上；不带 tag 装到的是 `latest` 上的 `0.1.0`，它只支持 `0.1.5`、`0.1.6` 线，在 `0.1.7` 上激活失败。等 DSH 把 `0.1.7` 推上 `latest`，本插件跟着回到 `latest`。
+
 然后重启 web profile。一个包就是全部：它自带 `dsh.bundle.patch` 把自己的 Host 半边插进 profile，`dsh.client` 声明让 web 端加载浏览器半边。
 
 ### 本地 / 离线安装
@@ -50,7 +54,7 @@ dsh plugin --profile web add dsh-quick-actions
 ```sh
 mkdir -p /tmp/quick-actions
 pnpm --filter dsh-quick-actions pack --pack-destination /tmp/quick-actions
-dsh plugin --profile web add /tmp/quick-actions/dsh-quick-actions-0.1.0.tgz
+dsh plugin --profile web add /tmp/quick-actions/dsh-quick-actions-0.2.0-rc.1.tgz
 ```
 
 上面的 `--filter` 形式在仓库任意位置都能用；如果你已经在包目录里，`pnpm pack --pack-destination /tmp/quick-actions` 即可。
@@ -118,6 +122,7 @@ pnpm 有一条供应链策略：拒绝发布时间在冷却窗口内（默认 24
 - `id` 必填、全目录唯一且**永久**。标签、图标、文本可以在同一个 `id` 下改；`confirm` 属于安全行为签名，要改就得换新 `id`——把文本改成以 `/` 开头（或改掉这一点）同样算。
 - `label`、`text` 必填；`icon`、`confirm` 可选，`confirm` 默认 `true`。
 - 预置无效（缺字段、`id` 重复、目录超过 50 条）会让**插件加载响亮失败**并一次列出所有问题，而不是静默截断。
+- `presets` 与你的动作数据同在这一行 `config` 下（见下文「Settings 路径」），本插件从不写它。它是 DSH 的 volatile 字段：profile 运行期间改动会即时反映到快捷动作上；此时若改出无效目录，快捷动作区域显示目录错误，重启 profile 时插件加载失败并列出问题。
 
 用户对预置只能隐藏或克隆，不能编辑或删除；克隆出来的是一条普通的自定义动作。
 
@@ -145,13 +150,31 @@ pnpm 有一条供应链策略：拒绝发布时间在冷却窗口内（默认 24
 
 ## Settings 路径
 
-用户数据落在 `<DSH_HOME>/settings.yaml`（`DSH_HOME` 未设置时是 `~/.dsh`）：
+用户数据是本插件装载条目 `composer-quick-actions` 自己的 Config。DSH Settings 把它写进**当前 profile** 的 `<DSH_HOME>/profiles/web/cordis.patch.yml`（`DSH_HOME` 未设置时是 `~/.dsh`），落在该 id 那一行的 `config` 下：
+
+```yaml
+- id: composer-quick-actions
+  name: dsh-quick-actions
+  config:
+    schemaVersion: 1
+    layout: bar
+    userActionsById: { ... }
+    actionOrder: [ ... ]
+    presetStateById: { ... }
+```
 
-- `composer-quick-actions` — **唯一的持久化命名空间**，存放布局、自定义动作、统一顺序和预置差异。
-- `composer-quick-actions-catalog` — 预置目录，只读，不写用户层，因此**不会**出现在这个文件里。
+- 这五个字段存放布局、自定义动作、统一顺序和预置差异，是**唯一的持久化数据**。同一行的 `config.presets` 是你声明的预置，本插件从不写它。
+- 数据按 profile 各存一份。第一次在管理面板里改动之前，这一行可能根本不存在；改回默认状态时 DSH 会把它删掉。
+- 本插件自带管理面板，因此关掉了 DSH 为它自动生成设置页。
 
 Host 是校验的唯一权威，启动时按当前目录对存放的数据做一次幂等规范化。界面的每次修改都带上预期 revision；发生冲突时会刷新到最新状态并请你确认后重试，绝不静默覆盖别人的写入。更高 `schemaVersion` 写下的数据原样保留，因此降级往返无损。
 
+### 从 DSH 0.1.5 / 0.1.6 迁移
+
+旧版数据存在 `<DSH_HOME>/settings.yaml` 的 `composer-quick-actions` section。DSH `0.1.7` 首次启动、全部插件就绪后，会把整份文件改名为 `settings.yaml.imported`，再把每个 section 导入同名插件条目——**只尝试这一次**，也只有最先启动的那个 profile 能导入。
+
+导入要成功，那一刻跑着的必须是本版插件。**先升级本插件，再升级 DSH**（或在同一次重启里一起完成）。若 DSH 先升了，旧插件在它上面激活失败，这次导入随之失败，数据原样留在 `settings.yaml.imported` 里。这时手工迁移：把那个 section 下的五个字段原样复制到上面那一行的 `config` 下，然后重启 profile。
+
 ## 升级、降级与卸载
 
 **升级 / 降级**：
@@ -170,13 +193,13 @@ dsh plugin --profile web add dsh-quick-actions@<version>
 dsh plugin --profile web remove dsh-quick-actions
 ```
 
-依赖与 `dsh.profile.bundles` 里的那一层会同时去掉，重启 profile 后动作不再出现。
+依赖与 `dsh.profile.bundles` 里的那一层会同时去掉，重启 profile 后动作不再出现。`cordis.patch.yml` 里 `id: composer-quick-actions` 那一行原样保留——你的动作都在它的 `config` 里，重装后按 id 接回，所以动作会回来。只卸不装时，profile 每次启动会为这行打一条 `patch: entry "composer-quick-actions" not found` 警告，不影响启动；按下面第 1 步删掉即可。
 
 **手工彻底清理**（卸载不做这些，因为重装应当恢复你的动作）：
 
-1. 从 `<DSH_HOME>/settings.yaml` 删掉 `composer-quick-actions` section，这是唯一保存用户数据的地方。
-2. 如果 `<DSH_HOME>/profiles/web/pnpm-workspace.yaml` 里有为本插件加过的条目，一并删掉。
-3. 如果在 profile 的 `cordis.patch.yml` 里给 `composer-quick-actions` 写过 `config`，把那段删掉。
+1. 从 `<DSH_HOME>/profiles/web/cordis.patch.yml` 删掉 `id: composer-quick-actions` 那一行，这是唯一保存用户数据（以及你声明的预置）的地方。
+2. 如果 `<DSH_HOME>/settings.yaml.imported` 里还留着 `composer-quick-actions` section，一并删掉。
+3. 如果 `<DSH_HOME>/profiles/web/pnpm-workspace.yaml` 里有为本插件加过的条目，一并删掉。
 4. 重启 profile。
 
 ## 开发