Merge pull request #785 from omdsh-dev/fix/native-leak-guard-tests
fix(native): 钉牢 files 接管泄漏的守护断言 + 记录两条不变量
This commit is contained in:
5 files changed
+305
-43
No files matched your search
@@ -17,7 +17,7 @@
|
|||||||
|
|
||||||
## 2. CI 挂载冒烟(`plugin-mount` job / `pnpm test:mount`)
|
## 2. CI 挂载冒烟(`plugin-mount` job / `pnpm test:mount`)
|
||||||
|
|
||||||
「npm 打包 → 真实挂载 → 无头渲染」门禁(证明打包产物在真实 DSH 挂载后不 crash):`pnpm build && pnpm pack` 产 tarball → `scripts/e2e-mount.sh` 装进全新 scratch profile(`dsh plugin --profile web add <tarball>`)并启动真实 `dsh web`(keyless,`--port 0`)→ `tests/e2e/mount.e2e.ts`(Playwright)断言 `[data-dsh-better-sidebar]` 挂载、无错误条/pageerror/console 错误,展开 DSH 原生右侧栏后经其 guide 页逐个打开本插件贡献的 tab 类型**以及宿主自己的终端条目**(必须恰好 1 条——多于 1 条即意味着插件又在遮蔽宿主),再经插件文件树(原生 `files` kind 接管)打开 seed 文件强制加载 editor chunk(`client-editor.js`),并跑 mermaid / README 预览与 sidechat 宿主路由烟测。**`browser` 不在这个清单里,而是显式断言缺席**:DSH 0.1.7 的 `ui-sidebar-browser` 只在 desktop profile 挂载(`web-app` 的 patch 里 `disabled: ctx.get('profileContext')?.name !== 'desktop'`),lane 全走 web profile,钉住「没有」比默默放过更能暴露宿主立场的变化。
|
「npm 打包 → 真实挂载 → 无头渲染」门禁(证明打包产物在真实 DSH 挂载后不 crash):`pnpm build && pnpm pack` 产 tarball → `scripts/e2e-mount.sh` 装进全新 scratch profile(`dsh plugin --profile web add <tarball>`)并启动真实 `dsh web`(keyless,`--port 0`)→ `tests/e2e/mount.e2e.ts`(Playwright)断言 `[data-dsh-better-sidebar]` 挂载、无错误条/pageerror/console 错误,展开 DSH 原生右侧栏后经其 guide 页逐个打开本插件贡献的 tab 类型**以及宿主自己的终端条目**(必须恰好 1 条——多于 1 条即意味着插件又在遮蔽宿主),再经插件文件树(原生 `files` kind 接管)打开 seed 文件强制加载 editor chunk(`client-editor.js`),并跑 mermaid / README 预览与 sidechat 宿主路由烟测。**`tests/e2e/native-reload.e2e.ts` 是同一 lane 里的第二条门**:它 `utimesSync` 已安装的 `lib/client.js`(**在钉住的宿主 0.1.7-rc.1 上**:HMR 每 500ms stat-poll,rev = `mtime/ctime/size` 的 sha1;DSH 源码树的新版本改成只比 `mtime+size` 并对**内容**取 sha1——pin 上调时这个触发器必须同步复核,否则该用例会红在替换断言上而不是静默失效)触发**页面内条目替换**,断言替换前后都无 `native register … error`、无诊断条、且 `files` 接管重新可用——这是唯一能在部署层复现「teardown 期间注册把 id 孤儿化」(见 §3.4 第 9 条)的用例,v0.22.0 上实测 3/3 红、修复后 3/3 绿。**`browser` 不在这个清单里,而是显式断言缺席**:DSH 0.1.7 的 `ui-sidebar-browser` 只在 desktop profile 挂载(`web-app` 的 patch 里 `disabled: ctx.get('profileContext')?.name !== 'desktop'`),lane 全走 web profile,钉住「没有」比默默放过更能暴露宿主立场的变化。
|
||||||
|
|
||||||
本地:`pnpm build && pnpm pack && pnpm exec playwright install chromium && pnpm test:mount`(`DSH_CMD` 未设时 `scripts/e2e-common.sh` 回退的 npx 钉版是 `DSH_NPX_SPEC`,默认 `@deepseek-ai/dsh@0.1.7-rc.1`——**不钉就会解析 `latest`,而 `latest` 仍是插件已不支持的 0.1.5 线**)。CI 钉 `@deepseek-ai/dsh@0.1.7-rc.1`(**pin 一律写精确版本号,不要写 `@alpha`**:rc.1 上线时 npm `alpha` 指的是 **0.1.7-alpha.2**,rc.1 走的是 `next`;`latest` 仍是 0.1.5-rc.3;peer 下限 `^0.1.7-rc.1`)。该步骤用 `NODE_OPTIONS=--max-old-space-size=4096`:钉版自身的传递依赖是浮动 `^` 范围,上游分阶段发布预发布版时(rc.2 于 2026-09-10 的 14:43–14:57 逐包上线)npm 会组出混合 peer 图,3062 条 ERESOLVE 后 OOM(exit 134);另一个失败模式是对未发布兄弟包 ETARGET,靠「钉一个已完整发布的版本」修掉。**不要加 `--legacy-peer-deps`**:它跳过的正是全局安装必须提供的 peer,`@deepseek-ai/dsh-app-boot` 在 boot 时 require 的 `@deepseek-ai/cordis-plugin-group` 是 peer 而非 dependency,加了它 CLI 直接 `ERR_MODULE_NOT_FOUND`(实测过一次,见 rc.2 计划 C 节)。`ci-windows` 的 `Test` 跑 `pnpm test:windows`(`--maxWorkers=1`)而非 `pnpm test`——多个 spec 真起进程(`smoke` / `install-powershell` / `git`),2 核 runner 上并行起 ConPTY / 冷启 `powershell.exe` 是超时与 worker 静默死亡的放大器;`vitest.config.ts` 的全局 `testTimeout: 15_000`(默认 5000 在 Windows 上对真起进程的用例太低,三个不同文件先后翻车)是配套的一半。e2e spec 命名 `*.e2e.ts` + vitest `exclude` 双保险;**改 `exclude` 必须保留默认排除项**(exclude 整体替换默认值)。
|
本地:`pnpm build && pnpm pack && pnpm exec playwright install chromium && pnpm test:mount`(`DSH_CMD` 未设时 `scripts/e2e-common.sh` 回退的 npx 钉版是 `DSH_NPX_SPEC`,默认 `@deepseek-ai/dsh@0.1.7-rc.1`——**不钉就会解析 `latest`,而 `latest` 仍是插件已不支持的 0.1.5 线**)。CI 钉 `@deepseek-ai/dsh@0.1.7-rc.1`(**pin 一律写精确版本号,不要写 `@alpha`**:rc.1 上线时 npm `alpha` 指的是 **0.1.7-alpha.2**,rc.1 走的是 `next`;`latest` 仍是 0.1.5-rc.3;peer 下限 `^0.1.7-rc.1`)。该步骤用 `NODE_OPTIONS=--max-old-space-size=4096`:钉版自身的传递依赖是浮动 `^` 范围,上游分阶段发布预发布版时(rc.2 于 2026-09-10 的 14:43–14:57 逐包上线)npm 会组出混合 peer 图,3062 条 ERESOLVE 后 OOM(exit 134);另一个失败模式是对未发布兄弟包 ETARGET,靠「钉一个已完整发布的版本」修掉。**不要加 `--legacy-peer-deps`**:它跳过的正是全局安装必须提供的 peer,`@deepseek-ai/dsh-app-boot` 在 boot 时 require 的 `@deepseek-ai/cordis-plugin-group` 是 peer 而非 dependency,加了它 CLI 直接 `ERR_MODULE_NOT_FOUND`(实测过一次,见 rc.2 计划 C 节)。`ci-windows` 的 `Test` 跑 `pnpm test:windows`(`--maxWorkers=1`)而非 `pnpm test`——多个 spec 真起进程(`smoke` / `install-powershell` / `git`),2 核 runner 上并行起 ConPTY / 冷启 `powershell.exe` 是超时与 worker 静默死亡的放大器;`vitest.config.ts` 的全局 `testTimeout: 15_000`(默认 5000 在 Windows 上对真起进程的用例太低,三个不同文件先后翻车)是配套的一半。e2e spec 命名 `*.e2e.ts` + vitest `exclude` 双保险;**改 `exclude` 必须保留默认排除项**(exclude 整体替换默认值)。
|
||||||
|
|
||||||
@@ -69,7 +69,7 @@
|
|||||||
6. **`@deepseek-ai/dsh-client-runtime` 包已消亡**(继任 seed 是裸名 `dsh-client-store`,无 `/client` 子路径):peerDependencies、devDependencies、`dsh.client.inject`、chunk externals 白名单(`src/client/chunk-loader.ts` / `tsdown.config.ts` / `tests/chunk-loader.spec.ts` / `tests/manifest-consistency.spec.ts` 四处同步)均已无该条目。
|
6. **`@deepseek-ai/dsh-client-runtime` 包已消亡**(继任 seed 是裸名 `dsh-client-store`,无 `/client` 子路径):peerDependencies、devDependencies、`dsh.client.inject`、chunk externals 白名单(`src/client/chunk-loader.ts` / `tsdown.config.ts` / `tests/chunk-loader.spec.ts` / `tests/manifest-consistency.spec.ts` 四处同步)均已无该条目。
|
||||||
7. **e2e scratch profile 的 `minimumReleaseAgeExclude` 含 `'@deepseek-ai/*'`**(`scripts/e2e-mount.sh` / `e2e-aggregate-mount.sh`,与仓库根 `pnpm-workspace.yaml` 同策):alpha 版本常在发布后 24h 内跑 lane,pnpm 11 的 `minimumReleaseAge` 默认会拒装新鲜包。
|
7. **e2e scratch profile 的 `minimumReleaseAgeExclude` 含 `'@deepseek-ai/*'`**(`scripts/e2e-mount.sh` / `e2e-aggregate-mount.sh`,与仓库根 `pnpm-workspace.yaml` 同策):alpha 版本常在发布后 24h 内跑 lane,pnpm 11 的 `minimumReleaseAge` 默认会拒装新鲜包。
|
||||||
8. **插件开发树的 dsh-* 传递 peer 需提升为 devDependencies**(alpha.3 首见):`dsh-subagent` 等 npm 包把 `dsh-attachment` 等 dsh-* 姊妹包声明为 peerDependencies(由宿主 bundle 树统一提供,宿主侧无此问题),插件仓库若只直接依赖其中一部分,其余 peer 在 pnpm 下会解析到树上残留的旧版——如 `dsh-attachment@0.1.1-rc.1` 缺 `admitPromptContent` 导出、`dsh-subagent` 产物 import 它时测试加载即崩。因此 devDependencies 需涵盖 dev 树实际触达的全部 peer(attachment / scope / session-projection / system-prompt / user-approval / util-time 等,与直接依赖同款精确钉版);**`@deepseek-ai/cordis` peer 自 alpha.3 起要求 `^4.0.2`,0.1.7-alpha.1 要求 `^4.0.3`,rc.1 起要求 `~4.0.4`**(rc.1 顺手把 vendor 一起抬了:cordis 4.0.4 / schemastery 3.18.4 / cordis-plugin-group 1.0.4 / cordis-plugin-include 1.0.9;loader 保持 1.0.5)。**rc.1 实测的教训**:只改 `dependencies` 里的 schemastery 和 peer 里的 cordis **不够**——`cordis-plugin-group` / `-include` 是 `dsh-app-boot` / `dsh-config-editor` 的**传递 peer**,pnpm 会继续沿用 lockfile 里的旧副本,`pnpm peers check` 一次报出四类 unmet peer;按本条把四个 vendor 包**显式钉进 devDependencies** 才收敛(这也是 rc.1 那条「DSH 内部引用一律精确版本」的 workspace-release-ranges 政策的直接后果)。适配新版本时先跑 `pnpm peers check`,把新失配的传递 peer 一并提升进 devDependencies。**0.1.7 新增的同类问题**见 §3.3 第 12 条(`ui-primitives` 的第二层裸 import)。例外:**`dsh-client-locale` 的 peer/devDep 允许落后于基线**的历史已消除,rc.1 起上游恢复发版,0.1.7 起与 DSH 同 tuple。
|
8. **插件开发树的 dsh-* 传递 peer 需提升为 devDependencies**(alpha.3 首见):`dsh-subagent` 等 npm 包把 `dsh-attachment` 等 dsh-* 姊妹包声明为 peerDependencies(由宿主 bundle 树统一提供,宿主侧无此问题),插件仓库若只直接依赖其中一部分,其余 peer 在 pnpm 下会解析到树上残留的旧版——如 `dsh-attachment@0.1.1-rc.1` 缺 `admitPromptContent` 导出、`dsh-subagent` 产物 import 它时测试加载即崩。因此 devDependencies 需涵盖 dev 树实际触达的全部 peer(attachment / scope / session-projection / system-prompt / user-approval / util-time 等,与直接依赖同款精确钉版);**`@deepseek-ai/cordis` peer 自 alpha.3 起要求 `^4.0.2`,0.1.7-alpha.1 要求 `^4.0.3`,rc.1 起要求 `~4.0.4`**(rc.1 顺手把 vendor 一起抬了:cordis 4.0.4 / schemastery 3.18.4 / cordis-plugin-group 1.0.4 / cordis-plugin-include 1.0.9;loader 保持 1.0.5)。**rc.1 实测的教训**:只改 `dependencies` 里的 schemastery 和 peer 里的 cordis **不够**——`cordis-plugin-group` / `-include` 是 `dsh-app-boot` / `dsh-config-editor` 的**传递 peer**,pnpm 会继续沿用 lockfile 里的旧副本,`pnpm peers check` 一次报出四类 unmet peer;按本条把四个 vendor 包**显式钉进 devDependencies** 才收敛(这也是 rc.1 那条「DSH 内部引用一律精确版本」的 workspace-release-ranges 政策的直接后果)。适配新版本时先跑 `pnpm peers check`,把新失配的传递 peer 一并提升进 devDependencies。**0.1.7 新增的同类问题**见 §3.3 第 12 条(`ui-primitives` 的第二层裸 import)。例外:**`dsh-client-locale` 的 peer/devDep 允许落后于基线**的历史已消除,rc.1 起上游恢复发版,0.1.7 起与 DSH 同 tuple。
|
||||||
9. **右侧栏是 DSH 原生栏,插件只提供 tab 类型**:聊天里一切文件打开(工具行 / 产物行 / 正文提及 / 行内代码路径)统一走 `ctx.sidebarRight.openResource(fileAddressFor(sessionId, cwd, path))`。插件的每个 `TabDescriptor` 注册成原生 tab 类型(`kind = descriptor.id`,`extension` 带)+ 原生 tab 体(`sidebar.right.pane.tab` keyed 槽,key = `dsh-better-sidebar:<id>`);`editor` 类型同时认领 `dsh-resource://file/**`(**但按 §3.2 第 5 条的清单让出一部分**),并接管内置 `files` 页面 kind(`openTab('files')` 打开插件文件树,注销即复位)。`ctx.sidebarRight.openTab/openResource/close` 只对**在屏会话**写入;跨会话用具体类上的 `openTabIn/openResourceIn/closeIn`。原生 tab 的插件侧状态在 `src/client/native/tab-adapter.tsx`。**注册必须等服务、不能等槽声明**:原生栏先声明 `sidebar.right.pane.tab` 再 `provide('sidebarRightTabs')`,真机 profile 上槽声明回调里 `ctx.get('sidebarRightTabs')` 仍是 undefined(实测 3 秒后才出现),按槽触发注册会静默什么都不注册且永不重试——用 `ctx.inject(['sidebarRightTabs'], cb)` 驱动类型注册(`tests/native-surface.spec.ts` 以「槽先触发、服务后到达」的顺序守护)。**0.1.6-alpha.2 起**:`SidebarRightGuideEntry.id` 必填且同 provider 内唯一(缺它会静默清空整个承载面);同 provider 的 guide 条目是**追加**关系,`chain` 那种「替换宿主条目」的语义只存在于 `conversation.chat.turnTail` 且已被上游改成 `list`。**0.1.7 起**:`sidebar-right` 本体的契约**零破坏**——槽名无改名、`SidebarRightTabDefinition` 没有新的必填字段、只有新增的可选 `keepMounted` 与 `ISidebarRight.mounted`,`openTabIn/openResourceIn/closeIn` 在具体 class 上字节不变;`tab.visible` 语义收紧为 `active && (...)`(全局面板/后台会话时 body 不挂载);持久化校验收紧(非根 / 列轴 / 嵌套 / 3+ docked pane 的 split 一律判非法**整份丢弃**,0.1.6 的 sidebar 自己产不出这种布局);`RightbarRoot` 现在为每个保留会话渲染一个隐藏 seat(`SidebarSessionViews`,未导出、插件拿不到)。原生 tab 体宿主 `.paneBody` 是**有确定高度的块级滚动容器**(非 flex 容器),native 适配层因此给每个 tab 体包一层 `height:100%` 的列 flex 宿主(`sidebar.module.css` 的 `.nativeTabHost`),tab 组件根继续用 `flex:1`/`height:100%`。全局面板(根级 `main` keyed 槽 + `sidebar.panellist` + `ctx.layout.selectPanel/beginNavigation`、`rightbar` 改根级并新增 `rightbar.session`)插件**不接入**,只做兼容。底部工作台的中心列锚点认 `[data-slot="main.conversation"]`(并跳过 `display: contents` 祖先,同时保留 alpha.1 的 `[data-slot="conversation"]`);文件地址语法跟随 alpha.2(`fileAddressFor` 一律 session 作用域、绝对路径保留前导 `/`、`parseFileAddress` 前缀解析并去 `?`/`#`)。**原生指南说明的 4 条上限(归属更正:这是 0.1.7-alpha.1 起就存在的既成事实,不是 rc.1 的变更)**:`ui-sidebar-right/src/client/tabs/guide/GuideBody.tsx` 的 `MAX_DESCRIBED_ENTRIES = 4` 及其判定行在 alpha.1 / alpha.2 / rc.1 三个 tag 上**逐字相同**,宿主终端的 guide 条目(`ui-sidebar-terminal/src/client/TerminalGuide.tsx`)也是 alpha.1 就有了,`ui-sidebar-terminal/src` 在 rc.1 **零改动**。含义不变:条目 ≤ 4 条才渲染说明,更长的列表是整列丢弃而不是截断——插件默认贡献 4 个 guide 条目(文件 / 文件变动 / 任务管理 / 侧边对话),与宿主的终端条目合计后可能超过 4 条,此时说明不渲染;插件**不恢复**旧的 `nativeGuideDesc` 通用兜底句。
|
9. **右侧栏是 DSH 原生栏,插件只提供 tab 类型**:聊天里一切文件打开(工具行 / 产物行 / 正文提及 / 行内代码路径)统一走 `ctx.sidebarRight.openResource(fileAddressFor(sessionId, cwd, path))`。插件的每个 `TabDescriptor` 注册成原生 tab 类型(`kind = descriptor.id`,`extension` 带)+ 原生 tab 体(`sidebar.right.pane.tab` keyed 槽,key = `dsh-better-sidebar:<id>`);`editor` 类型同时认领 `dsh-resource://file/**`(**但按 §3.2 第 5 条的清单让出一部分**),并接管内置 `files` 页面 kind(`openTab('files')` 打开插件文件树,注销即复位)。`ctx.sidebarRight.openTab/openResource/close` 只对**在屏会话**写入;跨会话用具体类上的 `openTabIn/openResourceIn/closeIn`。原生 tab 的插件侧状态在 `src/client/native/tab-adapter.tsx`。**注册必须等服务、不能等槽声明**:原生栏先声明 `sidebar.right.pane.tab` 再 `provide('sidebarRightTabs')`,真机 profile 上槽声明回调里 `ctx.get('sidebarRightTabs')` 仍是 undefined(实测 3 秒后才出现),按槽触发注册会静默什么都不注册且永不重试——用 `ctx.inject(['sidebarRightTabs'], cb)` 驱动类型注册(`tests/native-surface.spec.ts` 以「槽先触发、服务后到达」的顺序守护)。**0.1.6-alpha.2 起**:`SidebarRightGuideEntry.id` 必填且同 provider 内唯一(缺它会静默清空整个承载面);同 provider 的 guide 条目是**追加**关系,`chain` 那种「替换宿主条目」的语义只存在于 `conversation.chat.turnTail` 且已被上游改成 `list`。**0.1.7 起**:`sidebar-right` 本体的契约**零破坏**——槽名无改名、`SidebarRightTabDefinition` 没有新的必填字段、只有新增的可选 `keepMounted` 与 `ISidebarRight.mounted`,`openTabIn/openResourceIn/closeIn` 在具体 class 上字节不变;`tab.visible` 语义收紧为 `active && (...)`(全局面板/后台会话时 body 不挂载);持久化校验收紧(非根 / 列轴 / 嵌套 / 3+ docked pane 的 split 一律判非法**整份丢弃**,0.1.6 的 sidebar 自己产不出这种布局);`RightbarRoot` 现在为每个保留会话渲染一个隐藏 seat(`SidebarSessionViews`,未导出、插件拿不到)。原生 tab 体宿主 `.paneBody` 是**有确定高度的块级滚动容器**(非 flex 容器),native 适配层因此给每个 tab 体包一层 `height:100%` 的列 flex 宿主(`sidebar.module.css` 的 `.nativeTabHost`),tab 组件根继续用 `flex:1`/`height:100%`。全局面板(根级 `main` keyed 槽 + `sidebar.panellist` + `ctx.layout.selectPanel/beginNavigation`、`rightbar` 改根级并新增 `rightbar.session`)插件**不接入**,只做兼容。底部工作台的中心列锚点认 `[data-slot="main.conversation"]`(并跳过 `display: contents` 祖先,同时保留 alpha.1 的 `[data-slot="conversation"]`);文件地址语法跟随 alpha.2(`fileAddressFor` 一律 session 作用域、绝对路径保留前导 `/`、`parseFileAddress` 前缀解析并去 `?`/`#`)。**原生指南说明的 4 条上限(归属更正:这是 0.1.7-alpha.1 起就存在的既成事实,不是 rc.1 的变更)**:`ui-sidebar-right/src/client/tabs/guide/GuideBody.tsx` 的 `MAX_DESCRIBED_ENTRIES = 4` 及其判定行在 alpha.1 / alpha.2 / rc.1 三个 tag 上**逐字相同**,宿主终端的 guide 条目(`ui-sidebar-terminal/src/client/TerminalGuide.tsx`)也是 alpha.1 就有了,`ui-sidebar-terminal/src` 在 rc.1 **零改动**。含义不变:条目 ≤ 4 条才渲染说明,更长的列表是整列丢弃而不是截断——插件默认贡献 4 个 guide 条目(文件 / 文件变动 / 任务管理 / 侧边对话),与宿主的终端条目合计后可能超过 4 条,此时说明不渲染;插件**不恢复**旧的 `nativeGuideDesc` 通用兜底句。**原生注册账本的两条不变量(v0.22.1 起,由 `tests/native-registration.spec.ts` 守护)**:① `live` 里同时装着描述符类型(键 = descriptor id)与 `files` 接管(键 = `FILES_KIND`,**永远不在 `wanted` 里**),清理循环必须**跳过 `FILES_KIND`**——它只由编辑器类型的 `wantsFiles/hasFiles` 开关分支与 seat disposer 管理;否则每次通知都会把它拆掉再重建,而 teardown 期间的那次重建会把 id 孤儿化:`tabs.register` 建在**宿主** ctx 上(宿主 ctx 此时仍活着)所以照样成功,紧随的 `ctx.slots.inject` 建在**插件** ctx 上却抛 `cannot create effect on inactive context`,`live.set` 永不执行 → 该 id 在整页生命周期内不可再注册(真实表现:`native register files error: … already registered` 刷屏 + 文件树落到宿主空态,只有刷新页面才恢复;官方桌面壳日志实证见 [docs/plans/2026-09-28-native-files-takeover-reload-leak.md](docs/plans/2026-09-28-native-files-takeover-reload-leak.md))。② 因此「注册成功一半」是**可达状态*Line truncated
|
||||||
10. **自定义种子必须带 fork 标记对(`meta.isSeeded: true` + `inheritedEventCount`)**:dsh-session 契约「只给 seed 不标 isSeeded,种子算重放历史而非继承前缀」——缺标记时 `Session.ownEvents()` 含整个种子,子会话的 inbox 折重放种子里的 `agent/inbox/spliced`,**继承父会话切割时刻未领取的 inbox 输入**。宿主 `session.fork`(api-session-controller)的调用即规范形态;回归由 `tests/sidechat-seed-validation.spec.ts`(真实 `Session.create` + 对 `ownEvents()` 跑 inbox 折)守护。**0.1.7 复查:`Session.create` 的五个参数与函数体逐字相同**;上游新增了 `buildForkSeed(events, boundary)` 导出,与本插件手工的 `buildSidechatInheritance` 职责重叠但**收益不明确**(插件还有 dangling-tool-call 退回结构化快照的自有需求),暂不替换。
|
10. **自定义种子必须带 fork 标记对(`meta.isSeeded: true` + `inheritedEventCount`)**:dsh-session 契约「只给 seed 不标 isSeeded,种子算重放历史而非继承前缀」——缺标记时 `Session.ownEvents()` 含整个种子,子会话的 inbox 折重放种子里的 `agent/inbox/spliced`,**继承父会话切割时刻未领取的 inbox 输入**。宿主 `session.fork`(api-session-controller)的调用即规范形态;回归由 `tests/sidechat-seed-validation.spec.ts`(真实 `Session.create` + 对 `ownEvents()` 跑 inbox 折)守护。**0.1.7 复查:`Session.create` 的五个参数与函数体逐字相同**;上游新增了 `buildForkSeed(events, boundary)` 导出,与本插件手工的 `buildSidechatInheritance` 职责重叠但**收益不明确**(插件还有 dangling-tool-call 退回结构化快照的自有需求),暂不替换。
|
||||||
11. **`dsh.plugin.json` 从来不是 DSH 契约**:0.1.7 全树 grep 仍 **0 命中**。DSH 真正读的是 `package.json` 的 `dsh.bundle.patch` + `dsh.client`(`platform`/`inject`/`immediately`/`external`)+ `exports["./client"]`。`dsh.plugin.json` 只服务第三方 registry(社区市场)通道,`lib/client-registry.js` 同理;`tests/manifest-consistency.spec.ts` 守护的是这条通道的形状,不是 DSH 契约。**`dsh.manifestVersion` 也仍是「只声明、零读」**(0.1.7 的 `package-manifest` README 自己写明「Current installers and loaders do not enforce `dsh.manifestVersion` or `engines.dsh`」)。0.1.7 的官方管控面新增:`plugin-manager` 的**多 registry 回退**(`registryPlan()`:配置源 → `fallbackRegistries`(默认含 `registry.npmmirror.com`),`network`/`timeout`/`not-found`/`no-matching-version` 会自动问下一个源;`registry` 入参只存在于 Web 对话框与 `plugin_manager` 工具,**CLI 没有 registry flag**)、`waitForInstall`、以及**插件展示元数据**:`package.json#icon`(36×36、纯填充无描边、**双色渐变**——与 DSH 自带的 `PluginArtwork*` 同风格:它们「carry their own brand colors instead of riding currentColor」,且每个都是多色,单色版在 30px 行内尺寸下会读成一块纯色板)+ `locale/<lang>.json` 的 `meta.title`/`description`。本插件**已采纳**(v0.21.1):`icon.svg` + `locale/en.json` + `locale/zh.json`,并由 `tests/plugin-meta.spec.ts` 守护「声明了就必须发布出去」。**rc.1 复查:`packages/boot/app-boot/src/package-meta.ts` 与 `scripts/verify-package-meta.ts` 在两个 tag 上逐字相同**(`ui-plugin-manager/src/client/presentation.ts` 只多了一段 `incompatible-version` 文案),所以上面三条硬规则与「**没有任何尺寸/渐变校验**」都仍然成立。三条硬规则:icon 必须是**包内相对路径**且写进 `files`;`locale/en.json` 是发现基线(缺它整个目录都不读);`exports` 必须暴露 `./locale/*.json` 与 `./package.json`。**所有失败都是静默的**——元数据有问题只会退化成一行纯文字,没有任何报错。`dsh.bundle.patch` 现在多了形状校验(非法值会 `throw`,引导期跳过该 bundle),本插件是合法的单字符串。
|
11. **`dsh.plugin.json` 从来不是 DSH 契约**:0.1.7 全树 grep 仍 **0 命中**。DSH 真正读的是 `package.json` 的 `dsh.bundle.patch` + `dsh.client`(`platform`/`inject`/`immediately`/`external`)+ `exports["./client"]`。`dsh.plugin.json` 只服务第三方 registry(社区市场)通道,`lib/client-registry.js` 同理;`tests/manifest-consistency.spec.ts` 守护的是这条通道的形状,不是 DSH 契约。**`dsh.manifestVersion` 也仍是「只声明、零读」**(0.1.7 的 `package-manifest` README 自己写明「Current installers and loaders do not enforce `dsh.manifestVersion` or `engines.dsh`」)。0.1.7 的官方管控面新增:`plugin-manager` 的**多 registry 回退**(`registryPlan()`:配置源 → `fallbackRegistries`(默认含 `registry.npmmirror.com`),`network`/`timeout`/`not-found`/`no-matching-version` 会自动问下一个源;`registry` 入参只存在于 Web 对话框与 `plugin_manager` 工具,**CLI 没有 registry flag**)、`waitForInstall`、以及**插件展示元数据**:`package.json#icon`(36×36、纯填充无描边、**双色渐变**——与 DSH 自带的 `PluginArtwork*` 同风格:它们「carry their own brand colors instead of riding currentColor」,且每个都是多色,单色版在 30px 行内尺寸下会读成一块纯色板)+ `locale/<lang>.json` 的 `meta.title`/`description`。本插件**已采纳**(v0.21.1):`icon.svg` + `locale/en.json` + `locale/zh.json`,并由 `tests/plugin-meta.spec.ts` 守护「声明了就必须发布出去」。**rc.1 复查:`packages/boot/app-boot/src/package-meta.ts` 与 `scripts/verify-package-meta.ts` 在两个 tag 上逐字相同**(`ui-plugin-manager/src/client/presentation.ts` 只多了一段 `incompatible-version` 文案),所以上面三条硬规则与「**没有任何尺寸/渐变校验**」都仍然成立。三条硬规则:icon 必须是**包内相对路径**且写进 `files`;`locale/en.json` 是发现基线(缺它整个目录都不读);`exports` 必须暴露 `./locale/*.json` 与 `./package.json`。**所有失败都是静默的**——元数据有问题只会退化成一行纯文字,没有任何报错。`dsh.bundle.patch` 现在多了形状校验(非法值会 `throw`,引导期跳过该 bundle),本插件是合法的单字符串。
|
||||||
12. **peer 声明是启动期硬约束(rc.1 起;本版最容易静默失效的一处)**:`packages/boot/app-boot/src/plugin-compatibility.ts`(rc.1 **新文件**)只做一件事——遍历 profile 行的 `peerDependencies`,对**名字为 `@deepseek-ai/dsh` 或以 `@deepseek-ai/dsh-` 开头**的条目跑 `semver.satisfies(宿主版本, range, { includePrerelease: true })`,不满足就把整行 `row.disabled = true`(group 行连 `group` 一起关掉),只在 stderr 留一行 `disabling profile plugin <label>: <reason>`。调用点:`compatibility-preflight.ts` 的 `prepareProfileEntries`(`dsh web --profile <p>` 的必经路径)、`profile.ts`(bundle 行,异常被吞成 skip,该 bundle 不再贡献 patch 层)、`agent-preset-registry/src/mount.ts`(预置行),以及 plugin-manager 的安装前/安装后校验。**四个要点**:(a)它**只读 peer,不读 `engines.dsh` / `dsh.manifestVersion`**(那两个字段仍然零读者,见第 11 条);(b)`peerDependenciesMeta.optional` **没有任何豁免**——我们那条 optional 的 `@deepseek-ai/dsh-client-ui-sidebar-right` 照样参与判定;(c)`includePrerelease` 被强制打开,判定比 npm 宽松(`^0.1.6-alpha.2` 也能满足 `0.1.7-rc.1`),但**精确版本号、或没有预发布子句的范围(如 `^0.1.7`)一定不过**;(d)豁免只能写 profile 自己的 `compatibility.json`(`dsh plugin allow-version <pkg@ver> --dsh-version <exact> --accept-risk`),没有全局开关也没有环境变量。因此本仓库的 DSH peer **一律写 `^<基线>` 浮动范围、绝不钉精确版本**(devDependencies 才用精确钉版);`tests/market-manifest.spec.ts` 新增一条守护把这条规则钉住。**`pnpm peers check` 看不到这个失败模式**:它校验的是解析出来的 dev 树,不是宿主会读的范围形状。
|
12. **peer 声明是启动期硬约束(rc.1 起;本版最容易静默失效的一处)**:`packages/boot/app-boot/src/plugin-compatibility.ts`(rc.1 **新文件**)只做一件事——遍历 profile 行的 `peerDependencies`,对**名字为 `@deepseek-ai/dsh` 或以 `@deepseek-ai/dsh-` 开头**的条目跑 `semver.satisfies(宿主版本, range, { includePrerelease: true })`,不满足就把整行 `row.disabled = true`(group 行连 `group` 一起关掉),只在 stderr 留一行 `disabling profile plugin <label>: <reason>`。调用点:`compatibility-preflight.ts` 的 `prepareProfileEntries`(`dsh web --profile <p>` 的必经路径)、`profile.ts`(bundle 行,异常被吞成 skip,该 bundle 不再贡献 patch 层)、`agent-preset-registry/src/mount.ts`(预置行),以及 plugin-manager 的安装前/安装后校验。**四个要点**:(a)它**只读 peer,不读 `engines.dsh` / `dsh.manifestVersion`**(那两个字段仍然零读者,见第 11 条);(b)`peerDependenciesMeta.optional` **没有任何豁免**——我们那条 optional 的 `@deepseek-ai/dsh-client-ui-sidebar-right` 照样参与判定;(c)`includePrerelease` 被强制打开,判定比 npm 宽松(`^0.1.6-alpha.2` 也能满足 `0.1.7-rc.1`),但**精确版本号、或没有预发布子句的范围(如 `^0.1.7`)一定不过**;(d)豁免只能写 profile 自己的 `compatibility.json`(`dsh plugin allow-version <pkg@ver> --dsh-version <exact> --accept-risk`),没有全局开关也没有环境变量。因此本仓库的 DSH peer **一律写 `^<基线>` 浮动范围、绝不钉精确版本**(devDependencies 才用精确钉版);`tests/market-manifest.spec.ts` 新增一条守护把这条规则钉住。**`pnpm peers check` 看不到这个失败模式**:它校验的是解析出来的 dev 树,不是宿主会读的范围形状。
|
||||||
@@ -106,4 +106,4 @@
|
|||||||
- **接入 API 全参考**:[docs/external-plugin-guide.md](docs/external-plugin-guide.md)(消费插件开发者向;§0 原生栏承载面 / §4 Tab API / §5 FileViewer API / §7 服务方法 / §10 平台陷阱 / §11 已移除的自由窗口 / §12 皮肤契约 / §15 真实案例)。
|
- **接入 API 全参考**:[docs/external-plugin-guide.md](docs/external-plugin-guide.md)(消费插件开发者向;§0 原生栏承载面 / §4 Tab API / §5 FileViewer API / §7 服务方法 / §10 平台陷阱 / §11 已移除的自由窗口 / §12 皮肤契约 / §15 真实案例)。
|
||||||
- **设计文档**:[docs/plans/](docs/plans/)(30+ 份逐特性设计,含实施偏差记录)。
|
- **设计文档**:[docs/plans/](docs/plans/)(30+ 份逐特性设计,含实施偏差记录)。
|
||||||
- **测试不得依赖非普适二进制**:CI 跑 ubuntu + windows 两个 runner,`rg` / `fd` / `jq` 这类「开发机上有」的工具在 runner 上没有,代价是整个 spec 在**收集阶段**失败(`spawnSync rg ENOENT`)而本地永远绿——上一版的 `tests/primitives-exports.spec.ts` 就这么让分支红了两轮。取文件清单用 `readdirSync` 自己走,或只用 `git` / `tar` / `pnpm` / node 内置能力;确需外部工具时先探测存在性并跳过。
|
- **测试不得依赖非普适二进制**:CI 跑 ubuntu + windows 两个 runner,`rg` / `fd` / `jq` 这类「开发机上有」的工具在 runner 上没有,代价是整个 spec 在**收集阶段**失败(`spawnSync rg ENOENT`)而本地永远绿——上一版的 `tests/primitives-exports.spec.ts` 就这么让分支红了两轮。取文件清单用 `readdirSync` 自己走,或只用 `git` / `tar` / `pnpm` / node 内置能力;确需外部工具时先探测存在性并跳过。
|
||||||
- **关键测试守护**:`tests/service.spec.ts` / `builtins.spec.ts`(注册表与内置清单:**5 tab + 3 viewer**——终端与浏览器已交还宿主,只读预览也按 §3.2 第 5 条让出,只剩 markdown / html / code)/ `market-manifest.spec.ts`(市场约束,含 `pnpm pack` 后的产物面)/ `manifest-consistency.spec.ts`(registry 通道形状)/ `e2e-host-protocol.spec.ts`(RPC 双协议)/ `native-surface.spec.ts`(原生右侧栏承载面:guide 条目 id 唯一性、以及 `canOpen` 的「拒绝清单不得宽于宿主渲染器」双向边界)/ `theme.spec.ts`(皮肤契约,含空白面板胶囊几何)/ `plugin-list.spec.ts`(推荐插件目录)/ `fs-search.spec.ts`(host 文件名搜索)/ `fs-watch.spec.ts`(文件树目录 watch 的去抖、句柄上限与错误路径)/ `smoke.spec.ts` 的 settings 段(按 entry id 读写表单、**一次性 legacy 迁移**、open 工具门控)。
|
- **关键测试守护**:`tests/service.spec.ts` / `builtins.spec.ts`(注册表与内置清单:**5 tab + 3 viewer**——终端与浏览器已交还宿主,只读预览也按 §3.2 第 5 条让出,只剩 markdown / html / code)/ `market-manifest.spec.ts`(市场约束,含 `pnpm pack` 后的产物面)/ `manifest-consistency.spec.ts`(registry 通道形状)/ `e2e-host-protocol.spec.ts`(RPC 双协议)/ `native-surface.spec.ts`(原生右侧栏承载面:guide 条目 id 唯一性、以及 `canOpen` 的「拒绝清单不得宽于宿主渲染器」双向边界)/ `native-registration.spec.ts`(原生 tab 注册生命周期:`files` 接管不得被通知拆建、注册失败必须回滚已占用的 id 与已建槽位;断言写在注册表的事件日志上)/ `theme.spec.ts`(皮肤契约,含空白面板胶囊几何)/ `plugin-list.spec.ts`(推荐插件目录)/ `fs-search.spec.ts`(host 文件名搜索)/ `fs-watch.spec.ts`(文件树目录 watch 的去抖、句柄上限与错误路径)/ `smoke.spec.ts` 的 settings 段(按 entry id 读写表单、**一次性 legacy 迁移**、open 工具门控)。
|
||||||
@@ -0,0 +1,51 @@
|
|||||||
|
# `files` 接管 id 泄漏:客户端条目替换后报错刷屏 + 文件树空态
|
||||||
|
|
||||||
|
日期:2026-09-28 分支:`fix/native-registration-leak-v2`(PR #777,已合并)→ 后续 `fix/native-leak-guard-tests`
|
||||||
|
|
||||||
|
关联 issue:[#771](https://github.com/omdsh-dev/DSH-better-sidebar/issues/771)(同串报错的独立复现与定位)、[#770](https://github.com/omdsh-dev/DSH-better-sidebar/issues/770)(同串报错,另一条 inject re-prove 猜测)、[#766](https://github.com/omdsh-dev/DSH-better-sidebar/pull/766)(「吸收」方案,已按本文结论关闭)
|
||||||
|
|
||||||
|
## 现象
|
||||||
|
|
||||||
|
```
|
||||||
|
[dsh-better-sidebar] native register files error: sidebarRight: tab type id "dsh-better-sidebar:files" is already registered
|
||||||
|
```
|
||||||
|
|
||||||
|
红色诊断条钉在页面左下角、触发时**同一毫秒刷出多条**;不致命,但 `files`(文件树)接管会**静默缺位**——原生右侧栏的「文件」入口渲染成宿主的空态,直到**刷新页面**才恢复。0.21.1 与 0.22.0(npm `latest`)都带此缺陷。
|
||||||
|
|
||||||
|
## 根因(真机日志 + 代码双向验证)
|
||||||
|
|
||||||
|
官方桌面壳日志 `~/Library/Application Support/dsh-tauri/logs/desktop.frontdesk.log:2370`(2026-09-27 15:51:39.338)第一条就是完整栈:
|
||||||
|
|
||||||
|
```
|
||||||
|
native register files error: Error: cannot create effect on inactive context
|
||||||
|
assertActive ← effect ← inject(slots) ← registerSlots ← registerFilesKind ← sync ← notify
|
||||||
|
```
|
||||||
|
|
||||||
|
随后同一毫秒(.339–.340)**7 条** `already registered`(栈:`register ← registerFilesKind ← sync ← notify`),13 秒后新激活的 `_reload` 路径又报 2 条(该 burst 合计 9 条,与「7 个内置描述符注销 → 7 次 notify」一一对应)。链条:
|
||||||
|
|
||||||
|
1. `service.notify()` 是同步内联(`src/client/service.ts:696`),而 `registerNativeSurface` 把 `sync()` 订阅到它和 store 上(`src/client/native/index.ts:353`;本文行号按 v0.22.0,main 因 #777 的插入而顺移)。
|
||||||
|
2. `sync()` 的清理循环把 `live` 里**两类归属不同的条目**一视同仁:描述符类型(键 = descriptor id)与 `files` 接管(键 = `FILES_KIND`,**永远不在 `wanted` 里**)。于是**每次**通知都会释放接管、并在同一轮里重建它。
|
||||||
|
3. 插件 teardown 时,内置描述符逐个注销 → 每次注销 notify → `sync()` 在**已经 inactive** 的插件 ctx 上运行。此时 `tabs.register` 建在**宿主** ctx 上(宿主 ctx 仍活着)→ id 被取走且返回了 disposer;紧随的 `ctx.slots.inject` 建在**插件** ctx 上 → cordis `assertActive()` 抛 `INACTIVE_EFFECT`(`@deepseek-ai/cordis@4.0.4` `effect()` 首行)→ `live.set(FILES_KIND, …)` 永不执行 → **该 id 在本页生命周期内再也不能注册**。
|
||||||
|
4. 之后每次 notify(同一 burst 里还有 6 次)都重试同一个被占用的 id → `already registered` 刷屏;新一次激活同样注册不上 → 文件树空态。
|
||||||
|
|
||||||
|
**两条一般化的不变量**(已写进 [AGENTS.md](../../AGENTS.md) §3.4 第 9 条):
|
||||||
|
|
||||||
|
- 清理循环必须**跳过 `FILES_KIND`**;接管只由编辑器类型的 `wantsFiles/hasFiles` 分支与 seat disposer 管理。
|
||||||
|
- 「注册成功一半」是**可达状态**(宿主 ctx 与插件 ctx 的寿命不同),因此任何在宿主取走 id **之后**失败的注册必须**回滚释放该 type**(并释放已建槽位),插件侧只留一个下次通知可重试的失败。
|
||||||
|
|
||||||
|
## 修复
|
||||||
|
|
||||||
|
PR #777(贡献者 @yanzhaohui1999)落地上面两条:`sync()` 的清理循环跳过 `FILES_KIND`;`registerSlots` 失败时释放已建槽位;`registerDescriptor` / `registerFilesKind` 在槽位注册失败后回滚已占用的 type;teardown / 清理循环逐个安全释放(一个释放抛错不再中断其余)。
|
||||||
|
|
||||||
|
**否决备选方案**(PR #766 的「吸收」):把宿主抛出的 `already registered` 当作「宿主已持有该行」继续注册槽位。它能让日志安静,但会在 `live` 里记下一份**不拥有**的注册(空 disposer)——旧持有者随后释放该 id 时无人补注册,`files` 接管可能永久缺位;而且在 `tabs.register` 抛错(id 守卫,原子,未取走任何东西)与「取走后才失败」两种情形之间不做区分,掩盖了真正的账本错误。
|
||||||
|
|
||||||
|
## 验证
|
||||||
|
|
||||||
|
- **单测红→绿(实测)**:`tests/native-registration.spec.ts` 在 v0.22.0 源码上 4/4 红,在修复分支上 4/4 绿;`pnpm typecheck` / `pnpm lint` / `pnpm test` 全绿(修复分支的 base 早于 #781,故为 114 files / 1136 passed;合入 main 后为 122 files / 1292 passed / 9 skipped)。
|
||||||
|
- **部署级红→绿(实测)**:`tests/e2e/native-reload.e2e.ts` 在 scratch profile 里对 npm 上的 `dsh-better-sidebar@0.22.0` 触发页面内条目替换(`utimesSync` 已安装的 `lib/client.js`),**3/3 红**且每次都是本文那两条栈;换成本地打包的修复版 **3/3 绿**。该用例已随本 PR 进入挂载 lane(CI `plugin-mount` 绿),触发方式依赖钉住的宿主 0.1.7-rc.1 的 rev 规则(`mtime/ctime/size` 的 sha1)——pin 上调时需同步复核。
|
||||||
|
- 首版用例的两处断言(「失败后还能重新注册」)写在**活着的 id 集合**上,在未修复代码上会**同样通过**(泄漏的 id 恰好构成同一个集合)。跟进 PR 把它们改写到注册表的**事件日志**上,并把槽位失败判据从 `key` 改成 `name::key` —— 两个槽位共用一个 `key`,按 `key` 失败时**第一个**槽就抛,回收循环虽然进了、但手里的 disposer 列表永远是空的(即 `registerSlots` 的部分回滚**释放动作**从未被执行);改后可以让某个描述符的**第二个**槽失败,回收列表非空、释放路径真正被覆盖,且 4 例在 v0.22.0 上仍全部红。
|
||||||
|
|
||||||
|
## 已知限制 / 未做
|
||||||
|
|
||||||
|
- **跨激活的瞬时重复**仍未消除:页面内条目替换时,新激活可能先于旧激活释放 id 而撞上 `already registered`(一次日志噪音,随后自愈)。要消掉它需要「吸收 + 旧持有者释放后补注册」的机制,与上面否决的方案同源,暂不做。
|
||||||
|
- `disposeSafely` 的释放失败只写 `console.error`、**不弹诊断条**(teardown 阶段弹条是噪音;真被占住的 id 会在下一次注册尝试里经 `reportFailure` 显式报出)。理由写在源码注释里。
|
||||||
@@ -160,6 +160,13 @@ interface Registration {
|
|||||||
* Run one registration disposer, reporting a failure instead of propagating
|
* Run one registration disposer, reporting a failure instead of propagating
|
||||||
* it: releasing a registration must never mask the error being handled, and
|
* it: releasing a registration must never mask the error being handled, and
|
||||||
* one broken entry must not leave the others registered.
|
* one broken entry must not leave the others registered.
|
||||||
|
*
|
||||||
|
* A release failure is logged, NOT routed through `reportFailure` (the visible
|
||||||
|
* diagnostic strip), on purpose: both callers run while the surface is being
|
||||||
|
* taken down — the drop loop and the seat teardown — where a strip would just
|
||||||
|
* be noise, and an id that really stays taken cannot hide anyway: the next
|
||||||
|
* registration attempt for it goes through the strip as
|
||||||
|
* `register … error: … already registered`.
|
||||||
* @param dispose - the disposer to run.
|
* @param dispose - the disposer to run.
|
||||||
* @param what - the registration's name, for the log line.
|
* @param what - the registration's name, for the log line.
|
||||||
*/
|
*/
|
||||||
|
|||||||
@@ -0,0 +1,160 @@
|
|||||||
|
/**
|
||||||
|
* In-page CLIENT ENTRY REPLACEMENT ("plugin reload") — the deployment-level
|
||||||
|
* guard for the `dsh-better-sidebar:files` orphaned-tab-type bug.
|
||||||
|
*
|
||||||
|
* Field symptom (issues #770/#771, reproduced on the official desktop shell):
|
||||||
|
* a client-side replacement of the plugin entry — a plugin-market update, a
|
||||||
|
* disable→enable in the Plugins page, an HMR rebundle — left the host's tab
|
||||||
|
* type id `dsh-better-sidebar:files` registered with nobody holding its
|
||||||
|
* disposer, so the plugin could never register it again: every later `sync()`
|
||||||
|
* reported `native register files error: … already registered` and the Files
|
||||||
|
* takeover rendered the host's "nothing here can view this kind of content"
|
||||||
|
* face until a page refresh.
|
||||||
|
*
|
||||||
|
* Root cause (fixed in v0.22.1): `sync()`'s drop loop treated the plugin's own
|
||||||
|
* `files` takeover like a service descriptor, so every notification tore it
|
||||||
|
* down and re-created it in the same pass. During the reload the re-creation
|
||||||
|
* ran on the dying plugin context: `tabs.register` (host context, still alive)
|
||||||
|
* took the id and `ctx.slots.inject` (plugin context) then threw
|
||||||
|
* `cannot create effect on inactive context`, losing the disposer.
|
||||||
|
*
|
||||||
|
* The trigger here is the same one the host's own HMR uses: the installed
|
||||||
|
* client bundle is stat-polled, and a changed revision (`mtime`/`ctime`/`size`)
|
||||||
|
* makes the host tear the entry's fiber down and re-import it IN PAGE — no
|
||||||
|
* full page navigation, which is what made the old failure permanent.
|
||||||
|
*/
|
||||||
|
import { mkdirSync, utimesSync, writeFileSync } from 'node:fs'
|
||||||
|
import { tmpdir } from 'node:os'
|
||||||
|
import { join } from 'node:path'
|
||||||
|
import { test, expect, type APIRequestContext } from '@playwright/test'
|
||||||
|
import { PAGE_URL, createHostApi, hostRpc, sendFirstMessage } from './host'
|
||||||
|
|
||||||
|
/** Workspace the sidebar renders against (created by this lane's seeding). */
|
||||||
|
const WORKSPACE_PATH = process.env.DSH_E2E_WORKSPACE ?? join(tmpdir(), 'dsh-e2e-workspace')
|
||||||
|
|
||||||
|
/** A file seeded into the workspace, opened through the Files takeover. */
|
||||||
|
const SEEDED_FILE = 'hello.txt'
|
||||||
|
|
||||||
|
/**
|
||||||
|
* The installed client bundle the host's HMR stat-poll watches. Derived from
|
||||||
|
* the profile the server was booted with (`DSH_HOME`), overridable for a
|
||||||
|
* hand-run lane.
|
||||||
|
*/
|
||||||
|
const CLIENT_JS = process.env.DSH_E2E_PLUGIN_CLIENT_JS
|
||||||
|
?? (process.env.DSH_HOME === undefined
|
||||||
|
? undefined
|
||||||
|
: join(process.env.DSH_HOME, 'profiles/web/node_modules/dsh-better-sidebar/lib/client.js'))
|
||||||
|
|
||||||
|
/** The strip `fail()` pins to <body>; the plugin's registration failures land here. */
|
||||||
|
const REGISTRATION_ERROR = /native register .* error/
|
||||||
|
|
||||||
|
let api: APIRequestContext
|
||||||
|
|
||||||
|
test.beforeAll(async () => {
|
||||||
|
mkdirSync(WORKSPACE_PATH, { recursive: true })
|
||||||
|
writeFileSync(join(WORKSPACE_PATH, SEEDED_FILE), 'hello from the reload lane\n')
|
||||||
|
api = await createHostApi()
|
||||||
|
const workspace = await hostRpc<{ workspace: { workspaceId: string } }>(
|
||||||
|
api, 'workspace.create', { path: WORKSPACE_PATH },
|
||||||
|
)
|
||||||
|
await hostRpc(api, 'session.create', { workspaceId: workspace.value.workspace.workspaceId })
|
||||||
|
})
|
||||||
|
|
||||||
|
test.afterAll(async () => {
|
||||||
|
await api?.dispose()
|
||||||
|
})
|
||||||
|
|
||||||
|
test('the native tab types survive an in-page client entry replacement', async ({ page }) => {
|
||||||
|
// A hard failure, not a skip: this gate's whole value is that it cannot
|
||||||
|
// pass quietly when the harness stops telling us where the bundle lives.
|
||||||
|
if (CLIENT_JS === undefined) {
|
||||||
|
throw new Error('DSH_HOME (or DSH_E2E_PLUGIN_CLIENT_JS) must point at the profile running this server')
|
||||||
|
}
|
||||||
|
const consoleErrors: string[] = []
|
||||||
|
page.on('console', (message) => {
|
||||||
|
if (message.type() === 'error') consoleErrors.push(message.text())
|
||||||
|
})
|
||||||
|
|
||||||
|
await page.goto(PAGE_URL, { waitUntil: 'domcontentloaded' })
|
||||||
|
await expect(page.locator('#root > *')).not.toHaveCount(0, { timeout: 90_000 })
|
||||||
|
const sidebar = page.locator('[data-dsh-better-sidebar]')
|
||||||
|
await expect(sidebar).toBeAttached({ timeout: 90_000 })
|
||||||
|
|
||||||
|
// A keyless boot stacks onboarding takeovers over the shell (versioned
|
||||||
|
// welcome notice, then the provider-config dialog). Same bounded dismissal
|
||||||
|
// loop as the mount lane: a masked click is retried, an absent takeover is
|
||||||
|
// fine.
|
||||||
|
try {
|
||||||
|
await expect
|
||||||
|
.poll(() => page.getByRole('button', { name: /^(Continue|Configure later)$/ }).count(), { timeout: 60_000 })
|
||||||
|
.toBeGreaterThan(0)
|
||||||
|
} catch {
|
||||||
|
console.warn('[e2e] no onboarding takeover appeared; proceeding without dismissal')
|
||||||
|
}
|
||||||
|
for (let round = 0; round < 8; round++) {
|
||||||
|
let dismissed = false
|
||||||
|
for (const name of ['Continue', 'Configure later']) {
|
||||||
|
const button = page.getByRole('button', { name, exact: true }).first()
|
||||||
|
if ((await button.count()) === 0) continue
|
||||||
|
try {
|
||||||
|
await button.click({ timeout: 4_000 })
|
||||||
|
dismissed = true
|
||||||
|
await page.waitForTimeout(1_000)
|
||||||
|
} catch {
|
||||||
|
// Masked by the takeover stacked above it; the next round tries again.
|
||||||
|
}
|
||||||
|
}
|
||||||
|
if (!dismissed) break
|
||||||
|
}
|
||||||
|
|
||||||
|
// The session header (and with it the native right sidebar's controls) only
|
||||||
|
// exists once the session has a turn — the mount lane does the same.
|
||||||
|
await sendFirstMessage(page)
|
||||||
|
await page.locator('[data-sidebar-right-expand]').first().click()
|
||||||
|
const pane = page.locator('[data-sidebar-right-panel]')
|
||||||
|
await expect(page.locator('[data-sidebar-right-guide]')).toBeVisible({ timeout: 30_000 })
|
||||||
|
// The takeover is ALIVE before the reload: its guide row opens the plugin's
|
||||||
|
// explorer and the seeded file is listed.
|
||||||
|
await page.locator('[data-sidebar-right-guide-entry="files"]').click()
|
||||||
|
await expect(pane.locator(`[role="button"][title$="${SEEDED_FILE}"]:visible`)).toHaveCount(1, { timeout: 30_000 })
|
||||||
|
|
||||||
|
// ── Trigger: bump the installed bundle's revision ─────────────────────
|
||||||
|
// Tag the CURRENT host element so the replacement is observable: a disposal
|
||||||
|
// removes it (`host.remove()`), and the new activation appends a fresh one.
|
||||||
|
await page.evaluate(() => {
|
||||||
|
document.querySelector('[data-dsh-better-sidebar]')?.setAttribute('data-e2e-generation', 'before-reload')
|
||||||
|
})
|
||||||
|
const now = new Date()
|
||||||
|
utimesSync(CLIENT_JS!, now, new Date(now.getTime() + 2_000))
|
||||||
|
await expect(
|
||||||
|
page.locator('[data-dsh-better-sidebar][data-e2e-generation="before-reload"]'),
|
||||||
|
'the host must replace the plugin entry in page (new activation)',
|
||||||
|
).toHaveCount(0, { timeout: 60_000 })
|
||||||
|
// Let the fresh activation finish its registrations.
|
||||||
|
await expect(page.locator('[data-dsh-better-sidebar]')).toBeAttached({ timeout: 60_000 })
|
||||||
|
await page.waitForTimeout(2_000)
|
||||||
|
|
||||||
|
// ── Assertions: no registration failure, takeover usable ──────────────
|
||||||
|
const registrationErrors = consoleErrors.filter(message => REGISTRATION_ERROR.test(message))
|
||||||
|
expect(registrationErrors, registrationErrors.join('\n')).toEqual([])
|
||||||
|
await expect(
|
||||||
|
page.locator('body > div', { hasText: 'native register files error' }),
|
||||||
|
'the failure strip must not be pinned',
|
||||||
|
).toHaveCount(0)
|
||||||
|
// The Files takeover works again after the replacement: the guide row is
|
||||||
|
// offered and the explorer still lists the seeded file.
|
||||||
|
if (await page.locator('[data-sidebar-right-guide]').count() === 0) {
|
||||||
|
await page.locator('[data-dockkit-add-tab]').first().click()
|
||||||
|
}
|
||||||
|
const filesEntry = page.locator('[data-sidebar-right-guide-entry="files"]')
|
||||||
|
await expect(filesEntry, 'the Files guide row must be offered again').toHaveCount(1, { timeout: 30_000 })
|
||||||
|
await filesEntry.click()
|
||||||
|
// The explorer must really render again — assert the CONTENT first (a bare
|
||||||
|
// "no unavailable marker" check passes on an empty pane), then the host's
|
||||||
|
// "a kind with no registrant" fallback must be absent.
|
||||||
|
await expect(pane.locator(`[role="button"][title$="${SEEDED_FILE}"]:visible`)).toHaveCount(1, { timeout: 30_000 })
|
||||||
|
await expect(
|
||||||
|
pane.locator('[data-sidebar-right-unavailable]'),
|
||||||
|
'the host must not fall back to its "nothing can view this kind" face',
|
||||||
|
).toHaveCount(0)
|
||||||
|
})
|
||||||
@@ -14,12 +14,19 @@
|
|||||||
* `tab type id "…" is already registered`. The kind then renders the host's
|
* `tab type id "…" is already registered`. The kind then renders the host's
|
||||||
* "nothing here can view this kind of content" face until a page refresh.
|
* "nothing here can view this kind of content" face until a page refresh.
|
||||||
*
|
*
|
||||||
* Two properties keep that impossible, and both are asserted here:
|
* Three properties keep that impossible, and all are asserted here:
|
||||||
* 1. an unrelated notification never re-creates the `files` takeover (the
|
* 1. an unrelated notification never re-creates the `files` takeover (the
|
||||||
* tear-down/re-register window the reload used to walk into);
|
* tear-down/re-register window the reload used to walk into);
|
||||||
* 2. a registration that fails after its type was registered releases the
|
* 2. a registration that fails after its type was registered releases the
|
||||||
* type again, so the id stays registrable and one broken descriptor cannot
|
* type again, so the id stays registrable and one broken descriptor cannot
|
||||||
* take the others down with it.
|
* take the others down with it;
|
||||||
|
* 3. slots installed before the failing one are released too (the partial
|
||||||
|
* release inside `registerSlots`).
|
||||||
|
*
|
||||||
|
* The assertions are written against the fake registry's EVENT LOG, not only
|
||||||
|
* against the set of live ids: an orphaned type leaves the key set identical to
|
||||||
|
* a healthy one, so a key-set assertion would pass on the unfixed code and pin
|
||||||
|
* nothing.
|
||||||
*/
|
*/
|
||||||
import { describe, expect, it, vi } from 'vitest'
|
import { describe, expect, it, vi } from 'vitest'
|
||||||
import { registerNativeSurface } from '../src/client/native/index.ts'
|
import { registerNativeSurface } from '../src/client/native/index.ts'
|
||||||
@@ -44,8 +51,14 @@ function createRegistry() {
|
|||||||
throw new Error(`sidebarRight: tab type id "${definition.id}" is already registered`)
|
throw new Error(`sidebarRight: tab type id "${definition.id}" is already registered`)
|
||||||
}
|
}
|
||||||
events.push(`register ${definition.id}`)
|
events.push(`register ${definition.id}`)
|
||||||
|
// The host's disposer is IDEMPOTENT (a cordis effect disposer returns
|
||||||
|
// the same task on a second call), so a repeated release must neither
|
||||||
|
// log again nor pretend to free something twice.
|
||||||
|
let released = false
|
||||||
const dispose = (): void => {
|
const dispose = (): void => {
|
||||||
|
if (released) return
|
||||||
if (failReleaseOf === definition.id) throw new Error(`cannot release ${definition.id}`)
|
if (failReleaseOf === definition.id) throw new Error(`cannot release ${definition.id}`)
|
||||||
|
released = true
|
||||||
registered.delete(definition.id)
|
registered.delete(definition.id)
|
||||||
events.push(`release ${definition.id}`)
|
events.push(`release ${definition.id}`)
|
||||||
}
|
}
|
||||||
@@ -58,19 +71,28 @@ function createRegistry() {
|
|||||||
/**
|
/**
|
||||||
* A fake client context: `slots.inject` runs its callback synchronously (the
|
* A fake client context: `slots.inject` runs its callback synchronously (the
|
||||||
* real one resolves the declaration and calls `ctx.effect`, which throws while
|
* real one resolves the declaration and calls `ctx.effect`, which throws while
|
||||||
* `inactive`), `slots.register` throws for a key listed in `failKeys`, and
|
* `inactive`), a slot listed in `failSlots` throws from `slots.register`, and
|
||||||
* `inject` hands back the registry while honouring the callback's own teardown.
|
* `inject` hands back the registry while honouring the callback's own teardown.
|
||||||
|
*
|
||||||
|
* Slot failures are keyed by `name::key` — NOT by `key` alone. Both slots of a
|
||||||
|
* descriptor share the same key, so a key-keyed failure can only ever fail the
|
||||||
|
* FIRST slot; failing the second one for a single descriptor is the only shape
|
||||||
|
* that exercises `registerSlots`' partial release (the first slot is already
|
||||||
|
* installed when the second throws).
|
||||||
*/
|
*/
|
||||||
function createHost() {
|
function createHost() {
|
||||||
const registry = createRegistry()
|
const registry = createRegistry()
|
||||||
|
/** Slot registrations and releases, in order (the partial-release witness). */
|
||||||
|
const slotEvents: string[] = []
|
||||||
// One mutable state object the ctx closures read: the test flips it after
|
// One mutable state object the ctx closures read: the test flips it after
|
||||||
// the host was built.
|
// the host was built.
|
||||||
const state = {
|
const state = {
|
||||||
/** True while the plugin's context is being torn down (the reload case). */
|
/** True while the plugin's context is being torn down (the reload case). */
|
||||||
inactive: false,
|
inactive: false,
|
||||||
/** Native ids whose slot registration fails. */
|
/** `name::key` slots whose registration throws. */
|
||||||
failKeys: new Set<string>(),
|
failSlots: new Set<string>(),
|
||||||
}
|
}
|
||||||
|
const slotId = (options: { name: string; key?: string }): string => `${options.name}::${options.key ?? ''}`
|
||||||
const ctx = {
|
const ctx = {
|
||||||
inject: (
|
inject: (
|
||||||
_deps: readonly string[],
|
_deps: readonly string[],
|
||||||
@@ -85,15 +107,15 @@ function createHost() {
|
|||||||
if (state.inactive) throw new Error('cannot create effect on inactive context')
|
if (state.inactive) throw new Error('cannot create effect on inactive context')
|
||||||
return typeof callback === 'function' ? callback() : () => {}
|
return typeof callback === 'function' ? callback() : () => {}
|
||||||
},
|
},
|
||||||
register: (options: { key?: string }) => {
|
register: (options: { name: string; key?: string }) => {
|
||||||
if (options.key !== undefined && state.failKeys.has(options.key)) {
|
const id = slotId(options)
|
||||||
throw new Error(`slot registration for "${options.key}" failed`)
|
if (state.failSlots.has(id)) throw new Error(`slot registration for "${id}" failed`)
|
||||||
}
|
slotEvents.push(`register ${id}`)
|
||||||
return () => {}
|
return () => { slotEvents.push(`release ${id}`) }
|
||||||
},
|
},
|
||||||
},
|
},
|
||||||
}
|
}
|
||||||
return { registry, state, ctx }
|
return { registry, slotEvents, state, ctx }
|
||||||
}
|
}
|
||||||
|
|
||||||
/** A store + service with two enabled descriptors, plus the record registry. */
|
/** A store + service with two enabled descriptors, plus the record registry. */
|
||||||
@@ -115,31 +137,42 @@ function silenceFailures(): { restore: () => void; messages: string[] } {
|
|||||||
return { restore: () => { spy.mockRestore() }, messages }
|
return { restore: () => { spy.mockRestore() }, messages }
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* The phase labels a surface reports through the client's visible diagnostic
|
||||||
|
* channel (`reportFailure` → `fail('native ' + phase, error)`).
|
||||||
|
*/
|
||||||
|
function collectReports(): { phases: string[]; report: (phase: string) => void } {
|
||||||
|
const phases: string[] = []
|
||||||
|
return { phases, report: (phase: string) => { phases.push(phase) } }
|
||||||
|
}
|
||||||
|
|
||||||
describe('native tab registration lifecycle', () => {
|
describe('native tab registration lifecycle', () => {
|
||||||
it('releases a type whose slot registration failed, and can register it again later', () => {
|
it('releases a type whose slot registration failed, and can register it again later', () => {
|
||||||
const host = createHost()
|
const host = createHost()
|
||||||
const { store, service, records } = createPlugins()
|
const { store, service, records } = createPlugins()
|
||||||
const log = silenceFailures()
|
const reports = collectReports()
|
||||||
try {
|
// The reload: the context goes inactive while notifications are still
|
||||||
// The reload: the context goes inactive while notifications are still
|
// arriving, so every slot registration fails after its type registered.
|
||||||
// arriving, so every slot registration fails after its type registered.
|
host.state.inactive = true
|
||||||
host.state.inactive = true
|
expect(() => registerNativeSurface({
|
||||||
expect(() => registerNativeSurface({ ctx: host.ctx as never, store, service, records })).not.toThrow()
|
ctx: host.ctx as never, store, service, records, reportFailure: reports.report,
|
||||||
expect([...host.registry.registered.keys()], 'a failed registration leaves no type behind').toEqual([])
|
})).not.toThrow()
|
||||||
|
expect([...host.registry.registered.keys()], 'a failed registration leaves no type behind').toEqual([])
|
||||||
|
// Each of them is reported through the visible channel, not swallowed.
|
||||||
|
expect(reports.phases.sort()).toEqual(['register editor', 'register files', 'register git'])
|
||||||
|
|
||||||
// The context comes back (the reload's next activation): the same ids
|
// The context comes back (the reload's next activation): the same ids must
|
||||||
// must be registrable — no "already registered" from the orphan.
|
// be registrable — no "already registered" from the orphan. The event log
|
||||||
host.state.inactive = false
|
// is the discriminating assertion: a leaked type would keep the key set
|
||||||
host.state.failKeys.clear()
|
// looking correct while the retry throws into the same catch.
|
||||||
store.setPrefs(store.getPrefs())
|
host.state.inactive = false
|
||||||
expect([...host.registry.registered.keys()].sort()).toEqual([
|
host.registry.events.length = 0
|
||||||
'dsh-better-sidebar:editor',
|
store.setPrefs(store.getPrefs())
|
||||||
'dsh-better-sidebar:files',
|
expect(host.registry.events.sort()).toEqual([
|
||||||
'dsh-better-sidebar:git',
|
'register dsh-better-sidebar:editor',
|
||||||
])
|
'register dsh-better-sidebar:files',
|
||||||
} finally {
|
'register dsh-better-sidebar:git',
|
||||||
log.restore()
|
])
|
||||||
}
|
|
||||||
})
|
})
|
||||||
|
|
||||||
it('never re-creates the "files" takeover on an unrelated notification', () => {
|
it('never re-creates the "files" takeover on an unrelated notification', () => {
|
||||||
@@ -159,23 +192,34 @@ describe('native tab registration lifecycle', () => {
|
|||||||
it('keeps the other tab types when one descriptor cannot register', () => {
|
it('keeps the other tab types when one descriptor cannot register', () => {
|
||||||
const host = createHost()
|
const host = createHost()
|
||||||
const { store, service, records } = createPlugins()
|
const { store, service, records } = createPlugins()
|
||||||
host.state.failKeys.add('dsh-better-sidebar:git')
|
const reports = collectReports()
|
||||||
|
// The SECOND slot of ONE descriptor: its type and its body slot are
|
||||||
|
// already installed when this one throws.
|
||||||
|
host.state.failSlots.add('sidebar.right.pane.tab.title::dsh-better-sidebar:git')
|
||||||
const log = silenceFailures()
|
const log = silenceFailures()
|
||||||
try {
|
try {
|
||||||
expect(() => registerNativeSurface({ ctx: host.ctx as never, store, service, records })).not.toThrow()
|
expect(() => registerNativeSurface({
|
||||||
|
ctx: host.ctx as never, store, service, records, reportFailure: reports.report,
|
||||||
|
})).not.toThrow()
|
||||||
expect([...host.registry.registered.keys()].sort()).toEqual([
|
expect([...host.registry.registered.keys()].sort()).toEqual([
|
||||||
'dsh-better-sidebar:editor',
|
'dsh-better-sidebar:editor',
|
||||||
'dsh-better-sidebar:files',
|
'dsh-better-sidebar:files',
|
||||||
])
|
])
|
||||||
|
expect(reports.phases).toEqual(['register git'])
|
||||||
|
// The body slot installed before the failure was released; the failing
|
||||||
|
// one never registered, so there is nothing to release for it.
|
||||||
|
expect(host.slotEvents.filter(event => event === 'release sidebar.right.pane.tab::dsh-better-sidebar:git'))
|
||||||
|
.toHaveLength(1)
|
||||||
|
expect(host.slotEvents.filter(event => event === 'release sidebar.right.pane.tab.title::dsh-better-sidebar:git'))
|
||||||
|
.toEqual([])
|
||||||
|
|
||||||
// The broken descriptor is retried on the next sync instead of being
|
// The broken descriptor is retried on the next sync instead of being
|
||||||
// written off, and the retry succeeds once it can register.
|
// written off — and the retry REGISTERS it (event log), rather than
|
||||||
host.state.failKeys.clear()
|
// merely ending up with a key set a leaked type produces as well.
|
||||||
|
host.state.failSlots.clear()
|
||||||
|
host.registry.events.length = 0
|
||||||
store.setPrefs(store.getPrefs())
|
store.setPrefs(store.getPrefs())
|
||||||
expect([...host.registry.registered.keys()].sort()).toEqual([
|
expect(host.registry.events).toEqual(['register dsh-better-sidebar:git'])
|
||||||
'dsh-better-sidebar:editor',
|
|
||||||
'dsh-better-sidebar:files',
|
|
||||||
'dsh-better-sidebar:git',
|
|
||||||
])
|
|
||||||
} finally {
|
} finally {
|
||||||
log.restore()
|
log.restore()
|
||||||
}
|
}
|
||||||
|
|||||||
Reference in new issue
Block a user