@wangxiaocuo/dsh-session-trash 0.6.3 → 0.6.4

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 本文件记录这个插件的所有重要变更。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本号遵循[语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [Unreleased]
+
+## [0.6.4] - 2026-11-11
+
+### Added
+
+- e2e 支持 `DSH_E2E_DSH_BIN` 启动 npm 安装的 `@deepseek-ai/dsh` web Host，不再依赖桌面版；Linux/Windows 也能跑真实 Host 端到端测试。
+- CI 新增真实 Host e2e job（Ubuntu + Windows），失败时输出 check annotations。
+- 新增 `pnpm typecheck`（`tsc --checkJs`，先覆盖 `lib/` 和 `index.js`）并接入 CI；DSH 服务通过 `types/dsh-context.d.ts` 的 ambient 声明提供类型。
+- 新增 jsdom + 真实 React 渲染测试（`test/client-dom.test.js`），覆盖行菜单的方向键/Escape/Tab/外点关闭，以及确认对话框的焦点陷阱和焦点恢复。
+
+### Fixed
+
+- ActionMenu：Escape 不再冒泡到宿主设置弹层；Tab 会关闭菜单并让焦点自然移动；分隔符使用 `role="separator"`。
+- ConfirmDialog：打开它的行或按钮被移除后，焦点回退到列表面板，不再丢到 `body`。
+
 ## [0.6.3] - 2026-11-11
 
 ### Added
@@ -78,6 +94,7 @@
 
 - 回收站工具栏的「永久删除全部」与二次确认；`missing` 记录只移出索引，不删除会话文件。
 
+[0.6.4]: https://github.com/wangxiaocuo/dsh-session-trash/compare/v0.6.3...v0.6.4
 [0.6.3]: https://github.com/wangxiaocuo/dsh-session-trash/compare/v0.6.2...v0.6.3
 [0.6.2]: https://github.com/wangxiaocuo/dsh-session-trash/compare/v0.6.1...v0.6.2
 [0.6.1]: https://github.com/wangxiaocuo/dsh-session-trash/compare/v0.6.0...v0.6.1

package/README.en.md

@@ -6,7 +6,7 @@
 
 A session trash for DeepSeek Harness. Move cold sessions out of the sidebar without deleting their logs, restore them within the retention window, or delete the logs permanently. Built for DSH 0.2.2-rc.1 on Desktop and Web. Host and Client ship in one package, with no build step.
 
-Status: feature complete. CI (GitHub Actions) runs the unit and Host smoke tests on Ubuntu (Node 20/22) and Windows (Node 22); macOS has run the end-to-end suite against a real DSH Host. The Windows and Linux DSH Hosts have not been verified manually yet, and Windows skips the cases that rely on POSIX permission bits.
+Status: feature complete. CI (GitHub Actions) runs the unit tests, the Host smoke test, and the real `dsh web` end-to-end suite on Ubuntu (Node 20/22) and Windows (Node 22), booting the Host from an npm-installed DSH runtime; macOS also ran the suite against the real desktop Host manually. Windows skips the cases that rely on POSIX permission bits.
 
 ## Features
 
@@ -167,7 +167,7 @@ The index schema is v2; a v1 index is upgraded automatically on startup and pres
 - Permanent deletion removes the session log only. Attachments, images, projection-cache rows, and search-index rows are not deleted.
 - `/state` returns all entry summaries in one response. Search, filtering, and paging happen in the Client.
 - There is no cross-window live push. Another window's change appears after a refresh or when the window regains focus.
-- The Windows and Linux DSH Hosts have not been verified manually; CI covers unit and Host smoke tests only. On Windows, cases that rely on POSIX permission bits are skipped, and long paths over 260 characters / symlink copying depend on system configuration (the related tests skip themselves when unsupported).
+- The desktop apps on Windows and Linux have not been verified manually; CI boots an npm-installed `dsh web` Host, so desktop-shell UI and desktop-only features (such as reveal in the file manager) are still verified on macOS only. On Windows, cases that rely on POSIX permission bits are skipped, and long paths over 260 characters / symlink copying depend on system configuration (the related tests skip themselves when unsupported).
 - macOS path comparison is case-insensitive. On a case-sensitive APFS volume, paths that differ only by case are treated as the same location.
 - Multiple DSH processes sharing one `DSH_HOME` serialize trash operations through `.lock`. A process paused for more than 10 minutes can lose the lock to another process.
 
@@ -175,9 +175,10 @@ The index schema is v2; a v1 index is upgraded automatically on startup and pres
 
 ```bash
 pnpm install
-pnpm test          # unit tests
+pnpm test          # unit tests + real-DOM component tests (jsdom)
+pnpm typecheck     # tsc --checkJs (currently lib/ and index.js)
 pnpm test:smoke    # Host smoke test (real Cordis, plain Node)
-npm run test:e2e   # real dsh web end-to-end (needs the desktop app)
+npm run test:e2e   # real dsh web end-to-end (desktop app or npm-installed DSH)
 ```
 
 The Host smoke test wires the plugin into a real Cordis context through the `@deepseek-ai/cordis` devDependency, creates its own temporary `DSH_HOME`, and removes it afterwards; it does not need the desktop app. Set `DSH_SMOKE_KEEP=1` to keep the temporary home for debugging. `pnpm test` enumerates the test files through `test/run-unit.mjs`, so it does not depend on shell glob expansion and behaves the same on Windows and POSIX shells.
@@ -188,9 +189,10 @@ What CI verifies:
 |---|---|
 | Unit tests, Host smoke test | CI: Ubuntu Node 20/22, Windows Node 22 |
 | Package contents (`npm pack`) | CI: Ubuntu |
-| Real `dsh web` end to end | macOS + DSH 0.2.2-rc.1 (run manually) |
+| Real `dsh web` end to end (npm-installed DSH) | CI: Ubuntu, Windows (Node 22) |
+| Real `dsh web` end to end (desktop app) | macOS + DSH 0.2.2-rc.1 (run manually) |
 
-`npm run test:e2e` boots a real `dsh web` Host in a temporary `DSH_HOME` and runs the full flow. It discovers the desktop app in the platform's usual install locations, or uses `DSH_ELECTRON`; when no desktop app is found it prints a skip message and exits 0. The cleanup-failure scenario that relies on POSIX permission bits is skipped on Windows. Set `DSH_E2E_KEEP=1` to keep the temporary home and logs.
+`npm run test:e2e` boots a real `dsh web` Host in a temporary `DSH_HOME` and runs the full flow. By default it discovers the desktop app in the platform's usual install locations (or uses `DSH_ELECTRON`); set `DSH_E2E_DSH_BIN` to the `lib/bin.js` of an npm-installed `@deepseek-ai/dsh` to boot the Host with plain Node instead - CI and Linux/Windows use that mode, with no desktop app required. When no Host is found it prints a skip message and exits 0. The cleanup-failure scenario that relies on POSIX permission bits is skipped on Windows. Set `DSH_E2E_KEEP=1` to keep the temporary home and logs.
 
 Project layout:
 

package/README.md

@@ -6,7 +6,7 @@
 
 DeepSeek Harness 的会话回收站插件。冷会话可以从侧边栏移出，日志保留在本地；保留期内可以恢复，到期后自动删除日志。面向 DSH 0.2.2-rc.1 的 Desktop 和 Web，Host 和 Client 在同一个包里，不需要构建步骤。
 
-当前状态：功能已实现。CI（GitHub Actions）在 Ubuntu（Node 20/22）和 Windows（Node 22）上跑单元测试与 Host 冒烟测试；macOS 已在真实 DSH Host 上跑通端到端测试。Windows 和 Linux 的真实 DSH Host 尚未手动验证；Windows 上依赖 POSIX 权限位的用例会显式跳过。
+当前状态：功能已实现。CI（GitHub Actions）在 Ubuntu（Node 20/22）和 Windows（Node 22）上跑单元测试、Host 冒烟测试和真实 `dsh web` 端到端测试（Host 由 npm 安装的 DSH runtime 启动）；macOS 另外在真实桌面版 Host 上手动跑通过 e2e。Windows 上依赖 POSIX 权限位的用例会显式跳过。
 
 ## 功能
 
@@ -166,7 +166,7 @@ npm 安装的插件在「插件」页打开「会话回收站」的详情，展
 - 永久删除只删除会话日志。附件、图片、投影缓存和搜索索引不会被删除。
 - `/state` 一次返回全部条目摘要，页面在客户端搜索、筛选和分页。
 - 没有跨窗口实时推送。另一个窗口的变更要等刷新或窗口重新获得焦点后出现。
-- Windows 和 Linux 的真实 DSH Host 尚未手动验证；CI 只覆盖单元测试和 Host 冒烟测试。Windows 上依赖 POSIX 权限位的用例会跳过；超过 260 字符的长路径和符号链接复制受系统设置影响，对应用例在不支持时自动跳过。
+- Windows/Linux 的桌面版尚未手动验证；CI 用 npm 安装的 `dsh web` 覆盖真实 Host 行为，但桌面壳 UI 与桌面专属能力（例如「在文件管理器中显示」）仍只在 macOS 上验证。Windows 上依赖 POSIX 权限位的用例会跳过；超过 260 字符的长路径和符号链接复制受系统设置影响，对应用例在不支持时自动跳过。
 - macOS 的路径比较按大小写不敏感处理。在大小写敏感的 APFS 卷上，仅大小写不同的两个路径会被视为同一位置。
 - 多个 DSH 进程共享同一个 `DSH_HOME` 时，回收站操作通过 `.lock` 串行；进程暂停超过 10 分钟后，锁可能被另一个进程接管。
 
@@ -174,9 +174,10 @@ npm 安装的插件在「插件」页打开「会话回收站」的详情，展
 
 ```bash
 pnpm install
-pnpm test          # 单元测试
+pnpm test          # 单元测试 + 真实 DOM 组件测试（jsdom）
+pnpm typecheck     # tsc --checkJs（当前覆盖 lib/ 和 index.js）
 pnpm test:smoke    # Host 冒烟测试（真实 Cordis，普通 Node 即可）
-npm run test:e2e   # 真实 dsh web 端到端（需要本机桌面版）
+npm run test:e2e   # 真实 dsh web 端到端（桌面版或 npm 安装的 DSH）
 ```
 
 Host 冒烟测试通过 `@deepseek-ai/cordis` 这个 devDependency 装配真实插件上下文，自己创建并清理临时 `DSH_HOME`，不需要桌面版；设置 `DSH_SMOKE_KEEP=1` 可以保留临时目录用于排查。`pnpm test` 通过 `test/run-unit.mjs` 枚举测试文件，不依赖 shell 展开 glob，Windows 和 POSIX shell 行为一致。
@@ -187,9 +188,10 @@ Host 冒烟测试通过 `@deepseek-ai/cordis` 这个 devDependency 装配真实
 |---|---|
 | 单元测试、Host 冒烟测试 | CI：Ubuntu Node 20/22、Windows Node 22 |
 | 打包内容（`npm pack`） | CI：Ubuntu |
-| 真实 `dsh web` 端到端 | macOS + DSH 0.2.2-rc.1（手动执行） |
+| 真实 `dsh web` 端到端（npm 安装的 DSH） | CI：Ubuntu、Windows（Node 22） |
+| 真实 `dsh web` 端到端（桌面版） | macOS + DSH 0.2.2-rc.1（手动执行） |
 
-`npm run test:e2e` 会启动真实 `dsh web` Host，在临时 `DSH_HOME` 中跑完整流程。脚本会按平台在常见安装位置查找桌面版，也可以用 `DSH_ELECTRON` 指向其他 Electron 可执行文件；找不到桌面版时打印跳过信息并以 0 退出。依赖 POSIX 权限位的「清理失败」场景在 Windows 上会跳过。设置 `DSH_E2E_KEEP=1` 可以保留临时目录和日志。
+`npm run test:e2e` 会启动真实 `dsh web` Host，在临时 `DSH_HOME` 中跑完整流程。默认按平台在常见安装位置查找桌面版（也可以用 `DSH_ELECTRON` 指定）；设置 `DSH_E2E_DSH_BIN` 指向 npm 安装的 `@deepseek-ai/dsh` 的 `lib/bin.js` 时，改用普通 Node 启动 Host——CI 和 Linux/Windows 都走这条路径，不依赖桌面版。找不到 Host 时打印跳过信息并以 0 退出。依赖 POSIX 权限位的「清理失败」场景在 Windows 上会跳过。设置 `DSH_E2E_KEEP=1` 可以保留临时目录和日志。
 
 项目结构：
 

package/client.js

@@ -889,8 +889,14 @@ window.__ModuleLoader__.load({
           if (wrapRef.current !== null && !wrapRef.current.contains(event.target)) setOpen(false)
         }
         const onKeyDown = (event) => {
+          if (event.key === 'Tab') {
+            // Let focus leave the menu naturally; just stop leaving it open.
+            setOpen(false)
+            return
+          }
           if (event.key !== 'Escape') return
           event.preventDefault()
+          event.stopPropagation()
           setOpen(false)
           if (buttonRef.current !== null) buttonRef.current.focus()
         }
@@ -992,9 +998,11 @@ window.__ModuleLoader__.load({
               },
               items.map((item, index) =>
                 h(
-                  'div',
+                  React.Fragment,
                   { key: item.key },
-                  item.separatorBefore === true && index > 0 ? h('div', { className: 'dsh-trash__menuSeparator' }) : null,
+                  item.separatorBefore === true && index > 0
+                    ? h('div', { className: 'dsh-trash__menuSeparator', role: 'separator' })
+                    : null,
                   h(
                     'button',
                     {
@@ -1034,7 +1042,7 @@ window.__ModuleLoader__.load({
      * }} props dialog content and handlers.
      * @returns {import('react').ReactElement} the dialog overlay.
      */
-    function ConfirmDialog({ kind, entry, count, t, onCancel, onConfirm }) {
+    function ConfirmDialog({ kind, entry, count, t, onCancel, onConfirm, fallbackRef }) {
       const dialogRef = React.useRef(null)
       const cancelRef = React.useRef(null)
       const titleId = `dsh-trash-dialog-title-${kind}`
@@ -1068,7 +1076,12 @@ window.__ModuleLoader__.load({
         document.addEventListener('keydown', onKeyDown, true)
         return () => {
           document.removeEventListener('keydown', onKeyDown, true)
-          if (previous !== null && typeof previous.focus === 'function') previous.focus()
+          if (previous !== null && typeof previous.focus === 'function' && previous.isConnected !== false) {
+            previous.focus()
+            return
+          }
+          const fallback = fallbackRef === null || fallbackRef === undefined ? null : fallbackRef.current
+          if (fallback !== null && typeof fallback.focus === 'function') fallback.focus()
         }
       }, [onCancel])
 
@@ -2269,6 +2282,7 @@ window.__ModuleLoader__.load({
                   className: 'dsh-trash__panel',
                   key: 'panel',
                   ref: panelRef,
+                  tabIndex: -1,
                   'aria-busy': readsBusy ? 'true' : 'false',
                 },
                 panelBody,
@@ -2289,6 +2303,7 @@ window.__ModuleLoader__.load({
                 count: dialog.count,
                 t,
                 onCancel: closeDialog,
+                fallbackRef: panelRef,
                 onConfirm: () => {
                   const current = dialog
                   setDialog(null)

package/index.js

@@ -34,7 +34,7 @@ function createLogger(ctx) {
   const prefix = 'dsh-session-trash'
   let sink = null
   try {
-    const factory = ctx.get('logger')
+    const factory = /** @type {any} */ (ctx.get('logger'))
     if (typeof factory === 'function') {
       const instance = factory(prefix)
       if (instance !== null && instance !== undefined && typeof instance.info === 'function') sink = instance
@@ -65,7 +65,7 @@ function createLogger(ctx) {
  * recovery, and the retention sweep.
  *
  * @param {import('@deepseek-ai/cordis').Context} ctx plugin context.
- * @param {object} config validated plugin configuration.
+ * @param {any} config validated plugin configuration.
  * @returns {void}
  */
 export function apply(ctx, config) {

package/lib/cleanup.js

@@ -14,7 +14,7 @@ export const CLEANUP_RETRY_MAX_MS = 60 * 60 * 1000
 const STOPPED_RESULT = Object.freeze({ purged: 0, failed: 0, settled: 0 })
 
 /**
- * @param {unknown} error arbitrary failure.
+ * @param {any} error arbitrary failure.
  * @returns {string} a concise message.
  */
 function messageOf(error) {
@@ -22,7 +22,7 @@ function messageOf(error) {
 }
 
 /**
- * @param {unknown} error arbitrary failure.
+ * @param {any} error arbitrary failure.
  * @returns {string} a bounded diagnostic message for `/state`.
  */
 function errorText(error) {
@@ -60,18 +60,18 @@ function resolveTimer(ctx) {
  *
  * @param {{
  *   ctx: import('@deepseek-ai/cordis').Context,
- *   trashService: { sweep: (options: { allowPurge: boolean, now: number, reason: string }) => Promise<object> },
+ *   trashService: { sweep: (options: { allowPurge: boolean, now: number, reason: string }) => Promise<any> },
  *   config: { sweepIntervalHours: number, enableAutoCleanup: boolean },
  *   logger: { info: Function, warn: Function, error: Function, debug: Function },
  * }} deps host services and the configured cadence.
  * @returns {{
  *   start: () => void,
  *   stop: () => void,
- *   runNow: (options?: { manual?: boolean, reason?: string }) => Promise<object>,
+ *   runNow: (options?: { manual?: boolean, reason?: string }) => Promise<any>,
  *   maybeSweepOnPageOpen: () => void,
  *   nextSweepAt: () => number | null,
  *   lastSweepAt: () => number,
- *   diagnostics: () => object,
+ *   diagnostics: () => any,
  * }} the cleanup service.
  */
 export function createCleanupService({ ctx, trashService, config, logger }) {
@@ -91,7 +91,7 @@ export function createCleanupService({ ctx, trashService, config, logger }) {
   let disposeRetry = null
 
   /**
-   * @param {unknown} error sweep failure.
+   * @param {any} error sweep failure.
    * @returns {void}
    */
   function report(error) {
@@ -148,7 +148,7 @@ export function createCleanupService({ ctx, trashService, config, logger }) {
    * because an automatic sweep may have been started with `allowPurge: false`.
    *
    * @param {{ manual?: boolean, reason?: string }} [options] manual trigger and diagnostic label.
-   * @returns {Promise<object>} the sweep summary.
+   * @returns {Promise<any>} the sweep summary.
    */
   async function runNow(options = {}) {
     if (stopped) return { ...STOPPED_RESULT }
@@ -324,7 +324,7 @@ export function createCleanupService({ ctx, trashService, config, logger }) {
     /**
      * Read-only cleanup diagnostics for `/state` and the settings page.
      *
-     * @returns {object} a JSON-safe diagnostic snapshot.
+     * @returns {any} a JSON-safe diagnostic snapshot.
      */
     diagnostics() {
       return {

package/lib/eligibility.js

@@ -7,14 +7,14 @@ export const PREFLIGHT_TTL_MS = 2000
 
 /**
  * @typedef {{ sessionId: string, header: object }} DescendantRef
- * @typedef {{ sessionId: string, header: object, location: { path: string }, formatStatus?: string }} PlannedMember
+ * @typedef {{ sessionId: string, header: any, location: { path: string }, formatStatus?: string }} PlannedMember
  * @typedef {{ eligible: true, members: PlannedMember[] } | { eligible: false, code: string, message: string, details?: object }} PreflightResult
  */
 
 /**
  * @param {string} code refusal code.
  * @param {string} message owner-facing explanation.
- * @param {object} [details] optional structured context.
+ * @param {any} [details] optional structured context.
  * @returns {{ eligible: false, code: string, message: string, details?: object }} a refusal.
  */
 function refuse(code, message, details) {
@@ -24,7 +24,7 @@ function refuse(code, message, details) {
 /**
  * Collect every stored session whose lineage descends from `sessionId`.
  *
- * @param {import('@deepseek-ai/dsh-session-persistence').SessionPersistence} persistence persistence service.
+ * @param {any} persistence persistence service.
  * @param {string} sessionId root session.
  * @returns {Promise<DescendantRef[]>} descendant identity and stored header.
  */
@@ -59,7 +59,7 @@ async function descendantsFromListing(persistence, sessionId) {
  * A grandchild whose direct parent is no longer stored still proves that the
  * root session owns a lineage the trash must not split.
  *
- * @param {readonly object[]} nodes descendant nodes from the trace.
+ * @param {readonly any[]} nodes descendant nodes from the trace.
  * @returns {DescendantRef[]} every descendant session identity and header.
  */
 function collectTraceDescendants(nodes) {
@@ -123,7 +123,7 @@ export function createEligibility({ ctx, store, logger }) {
 
   /**
    * @param {string} sessionId descendant session to validate.
-   * @returns {Promise<object>} either `{ member }` with the planned member or `{ refusal }`.
+   * @returns {Promise<any>} either `{ member }` with the planned member or `{ refusal }`.
    */
   async function planDescendant(sessionId) {
     let snapshot

package/lib/errors.js

@@ -43,7 +43,7 @@ export class TrashError extends Error {
   /**
    * @param {string} code stable error code.
    * @param {string} message owner-facing explanation.
-   * @param {object} [details] optional structured context.
+   * @param {any} [details] optional structured context.
    */
   constructor(code, message, details) {
     super(message)
@@ -54,7 +54,7 @@ export class TrashError extends Error {
 }
 
 /**
- * @param {unknown} error arbitrary thrown value.
+ * @param {any} error arbitrary thrown value.
  * @returns {number} HTTP status for this error.
  */
 export function statusOf(error) {
@@ -86,8 +86,8 @@ const SAFE_DETAIL_KEYS = new Set([
  * Metrics snapshots are the only nested detail value the Host returns; keep
  * only their numeric counters so no path can ride along.
  *
- * @param {unknown} value candidate metrics object.
- * @returns {object | undefined} the numeric metrics.
+ * @param {any} value candidate metrics object.
+ * @returns {any | undefined} the numeric metrics.
  */
 function sanitizeMetrics(value) {
   if (value === null || typeof value !== 'object' || Array.isArray(value)) return undefined
@@ -99,8 +99,8 @@ function sanitizeMetrics(value) {
 }
 
 /**
- * @param {unknown} details arbitrary structured context.
- * @returns {object | undefined} the same context restricted to whitelisted keys.
+ * @param {any} details arbitrary structured context.
+ * @returns {any | undefined} the same context restricted to whitelisted keys.
  */
 export function sanitizeDetails(details) {
   if (details === null || typeof details !== 'object' || Array.isArray(details)) return undefined
@@ -122,7 +122,7 @@ export function sanitizeDetails(details) {
 }
 
 /**
- * @param {unknown} error arbitrary thrown value.
+ * @param {any} error arbitrary thrown value.
  * @returns {{ code: string, message: string, details?: object }} the wire error shape.
  */
 export function toWireError(error) {

package/lib/fsops.js

@@ -36,7 +36,7 @@ const COPY_OPTIONS = {
 }
 
 /**
- * @param {unknown} error thrown filesystem failure.
+ * @param {any} error thrown filesystem failure.
  * @returns {string | undefined} the Node error code.
  */
 export function errorCode(error) {
@@ -194,7 +194,7 @@ export function isInside(root, target) {
 }
 
 /**
- * @param {unknown} trashId candidate object identity.
+ * @param {any} trashId candidate object identity.
  * @returns {boolean} whether the identity is one safe path segment.
  */
 export function isSafeTrashId(trashId) {
@@ -214,7 +214,7 @@ export function isSafeTrashId(trashId) {
  * object. Session ids are `session-<uuid>` or a bare uuid today, so the
  * accepted alphabet is deliberately conservative.
  *
- * @param {unknown} sessionId candidate member identity.
+ * @param {any} sessionId candidate member identity.
  * @returns {boolean} whether the identity is one safe path segment.
  */
 export function isSafeMemberId(sessionId) {
@@ -286,8 +286,8 @@ export async function measureDirectory(directory) {
 }
 
 /**
- * @param {{ sizeBytes?: number | null, fileCount?: number | null } | null | undefined} entry index entry.
- * @param {{ sizeBytes: number, fileCount: number }} measured current metrics.
+ * @param {{ sizeBytes?: number | null, fileCount?: number | null, symlinkCount?: number | null } | null | undefined} entry index entry.
+ * @param {{ sizeBytes: number, fileCount: number, symlinkCount?: number }} measured current metrics.
  * @returns {boolean} whether the recorded metrics are absent or match exactly.
  */
 export function metricsMatch(entry, measured) {
@@ -303,7 +303,7 @@ export function metricsMatch(entry, measured) {
 }
 
 /**
- * @param {{ sizeBytes?: number | null, fileCount?: number | null } | null | undefined} entry index entry.
+ * @param {{ sizeBytes?: number | null, fileCount?: number | null, symlinkCount?: number | null } | null | undefined} entry index entry.
  * @returns {boolean} whether the entry carries a complete move snapshot.
  */
 export function hasMetrics(entry) {
@@ -339,7 +339,7 @@ export function createTrashId() {
  * @param {string} destination final directory path.
  * @param {{ sizeBytes: number, fileCount: number }} expected recorded metrics.
  * @param {(from: string, to: string) => Promise<void>} rename rename implementation for tests.
- * @param {(source: string, destination: string, options: object) => Promise<void>} copy copy implementation for tests.
+ * @param {(source: string, destination: string, options: any) => Promise<void>} copy copy implementation for tests.
  * @returns {Promise<void>} resolution after the destination is published.
  */
 async function copyAcrossDevices(source, destination, expected, rename, copy) {
@@ -382,7 +382,7 @@ async function copyAcrossDevices(source, destination, expected, rename, copy) {
  * @param {{
  *   logger?: { warn: Function },
  *   rename?: (from: string, to: string) => Promise<void>,
- *   copy?: (source: string, destination: string, options: object) => Promise<void>,
+ *   copy?: (source: string, destination: string, options: any) => Promise<void>,
  * }} [options] diagnostics sink and test seams.
  * @returns {Promise<void>} resolution after the directory lives at `destination`.
  */

package/lib/http.js

@@ -45,7 +45,7 @@ function headerBag(req) {
 /**
  * @param {import('node:http').ServerResponse} res response to complete.
  * @param {number} status HTTP status.
- * @param {unknown} body JSON-serializable body.
+ * @param {any} body JSON-serializable body.
  * @returns {void}
  */
 function sendJson(res, status, body) {
@@ -62,7 +62,7 @@ function sendJson(res, status, body) {
 
 /**
  * @param {import('node:http').ServerResponse} res response to complete.
- * @param {unknown} error thrown failure.
+ * @param {any} error thrown failure.
  * @returns {void}
  */
 function sendError(res, error) {
@@ -151,20 +151,24 @@ function requireSessionId(body) {
  * @param {{
  *   ctx: import('@deepseek-ai/cordis').Context,
  *   eligibility: { evaluate: Function, invalidate: Function },
- *   stateService: { snapshot: () => Promise<object>, describe: (entry: object) => Promise<object> },
+ *   stateService: { snapshot: () => Promise<any>, describe: (entry: any) => Promise<any> },
  *   trashService: {
- *     trash: (sessionId: string) => Promise<object>,
- *     restore: (sessionId: string, mode?: string) => Promise<object>,
- *     purge: (sessionId: string) => Promise<object>,
- *     purgeAll: () => Promise<object>,
- *     forget: (sessionId: string) => Promise<object>,
- *     reveal: (sessionId: string, signal?: AbortSignal) => Promise<object>,
- *     rebuild: () => Promise<object>,
+ *     trash: (sessionId: string) => Promise<any>,
+ *     restore: (sessionId: string, mode?: string) => Promise<any>,
+ *     purge: (sessionId: string) => Promise<any>,
+ *     purgeAll: () => Promise<any>,
+ *     forget: (sessionId: string) => Promise<any>,
+ *     reveal: (sessionId: string, signal?: AbortSignal) => Promise<any>,
+ *     rebuild: () => Promise<any>,
  *   },
- *   cleanupService?: { runNow: (options?: object) => Promise<object>, maybeSweepOnPageOpen: () => void },
+ *   cleanupService?: {
+    runNow: (options?: any) => Promise<any>,
+    maybeSweepOnPageOpen: () => void,
+    diagnostics?: () => any,
+  },
  *   ready: Promise<unknown>,
- *   config: object,
- *   logger: object,
+ *   config: any,
+ *   logger: any,
  * }} deps host services.
  * @returns {void}
  */
@@ -292,7 +296,11 @@ export function registerApi({ ctx, eligibility, stateService, trashService, clea
   route('restore', 'POST', async (req, res) => {
     const body = await readJsonRequest(req)
     const sessionId = requireSessionId(body)
-    const mode = body.mode
+    const rawMode = body.mode
+    if (rawMode !== undefined && typeof rawMode !== 'string') {
+      throw new TrashError('INVALID_REQUEST', 'mode must be "normal" or "orphan".')
+    }
+    const mode = typeof rawMode === 'string' ? rawMode : undefined
     if (mode !== undefined && mode !== 'normal' && mode !== 'orphan') {
       throw new TrashError('INVALID_REQUEST', 'mode must be "normal" or "orphan".')
     }

package/lib/inventory.js

@@ -17,7 +17,7 @@ const META_VERSION = 2
 const MAX_MEMBERS = 64
 
 /**
- * @param {unknown} value candidate timestamp.
+ * @param {any} value candidate timestamp.
  * @returns {boolean} whether the value is a finite number.
  */
 function isFiniteNumber(value) {
@@ -25,7 +25,7 @@ function isFiniteNumber(value) {
 }
 
 /**
- * @param {unknown} value candidate metric.
+ * @param {any} value candidate metric.
  * @returns {boolean} whether the value is a usable number or absent.
  */
 function isMetric(value) {
@@ -36,7 +36,7 @@ function isMetric(value) {
  * Validate one v2 member's absolute paths. The parent's sidecar is validated
  * field by field so a hand-edited file is rejected instead of guessed at.
  *
- * @param {unknown} member candidate member.
+ * @param {any} member candidate member.
  * @returns {boolean} whether the member names safe, coherent paths.
  */
 function isValidMemberPaths(member) {
@@ -72,7 +72,7 @@ function isValidMemberPaths(member) {
 /**
  * Validate the v2 member list of one sidecar.
  *
- * @param {object} meta candidate sidecar.
+ * @param {any} meta candidate sidecar.
  * @returns {boolean} whether the list is coherent with its parent fields.
  */
 function isValidMetaMembers(meta) {
@@ -100,7 +100,7 @@ function isValidMetaMembers(meta) {
  * entry. A malformed sidecar is reported as an unindexed object instead of
  * being guessed at.
  *
- * @param {unknown} meta parsed `meta.json`.
+ * @param {any} meta parsed `meta.json`.
  * @param {string} trashId object directory identity.
  * @returns {boolean} whether the sidecar can rebuild one entry.
  */
@@ -132,9 +132,9 @@ export function isValidMeta(meta, trashId) {
 }
 
 /**
- * @param {Record<string, unknown>} member raw member fields.
+ * @param {any} member raw member fields.
  * @param {string} fallbackTitle title used when the member carries none.
- * @returns {object} one normalized v2 member.
+ * @returns {any} one normalized v2 member.
  */
 function toMember(member, fallbackTitle) {
   return {
@@ -151,8 +151,8 @@ function toMember(member, fallbackTitle) {
 }
 
 /**
- * @param {Record<string, unknown>} meta valid sidecar.
- * @returns {object} a clean index entry with defaulted optional fields.
+ * @param {any} meta valid sidecar.
+ * @returns {any} a clean index entry with defaulted optional fields.
  */
 export function toEntry(meta) {
   const originalCwd = typeof meta.originalCwd === 'string' && meta.originalCwd !== '' ? meta.originalCwd : null
@@ -201,7 +201,7 @@ export function toEntry(meta) {
  * Which of one entry's member directories currently exist inside its object.
  *
  * @param {import('./store.js').TrashStore} store trash store owning `objects/`.
- * @param {object} entry index entry, v1 or v2 shaped.
+ * @param {any} entry index entry, v1 or v2 shaped.
  * @returns {Promise<{ total: number, present: number, missing: string[] }>} presence summary.
  */
 export async function memberPresence(store, entry) {
@@ -229,8 +229,8 @@ export async function memberPresence(store, entry) {
  * Whether two member lists name the same directories in the same order, so a
  * presence probe taken for one can be reused for the other.
  *
- * @param {readonly object[]} left first member list.
- * @param {readonly object[]} right second member list.
+ * @param {readonly any[]} left first member list.
+ * @param {readonly any[]} right second member list.
  * @returns {boolean} whether both lists describe the same members.
  */
 function sameMembers(left, right) {
@@ -244,10 +244,10 @@ function sameMembers(left, right) {
 /**
  * Reconcile a rebuilt entry with the object directory observed on disk.
  *
- * @param {object} entry index-shaped entry.
+ * @param {any} entry index-shaped entry.
  * @param {{ total: number, present: number, missing: string[] }} presence member presence.
  * @param {number} now current timestamp.
- * @returns {object} the entry whose state matches the filesystem.
+ * @returns {any} the entry whose state matches the filesystem.
  */
 export function deriveEntry(entry, presence, now) {
   const complete = presence.total > 0 && presence.present === presence.total
@@ -282,7 +282,7 @@ export function deriveEntry(entry, presence, now) {
  *
  * @param {import('./store.js').TrashStore} store trash store owning `objects/`.
  * @param {{ warn: Function }} logger diagnostics sink.
- * @returns {Promise<{ objects: { trashId: string, sessionExists: boolean, meta: object | undefined, metaValid: boolean, entry?: object, presence?: object }[], unindexed: number }>} the inventory.
+ * @returns {Promise<{ objects: { trashId: string, sessionExists: boolean, meta: any | undefined, metaValid: boolean, entry?: any, presence?: object }[], unindexed: number }>} the inventory.
  */
 export async function scanObjects(store, logger) {
   let entries
@@ -342,7 +342,7 @@ export async function scanObjects(store, logger) {
  * directory.
  *
  * @param {{ store: import('./store.js').TrashStore, logger: { warn: Function }, now?: number }} input trash store and diagnostics.
- * @returns {Promise<{ imported: number, markedMissing: number, unindexed: number, changed: number, presence: Map<string, object> }>} reconcile summary plus the presence probe per object.
+ * @returns {Promise<{ imported: number, markedMissing: number, unindexed: number, changed: number, presence: Map<string, any> }>} reconcile summary plus the presence probe per object.
  */
 export async function reconcileIndex({ store, logger, now = Date.now() }) {
   if (store.isProtected()) {