dsh-disk-cleaner 1.6.0 → 1.6.2

package/README.md

@@ -5,7 +5,7 @@
 <!-- badges -->
 | | |
 | --- | --- |
-| **version** | `1.6.0` |
+| **version** | `1.6.2` |
 | **DSH** | `0.2.1-rc.5`（开发与实测版本；用到 `plugins.bundle.config`、`settings.section`） |
 | **license** | [MIT](LICENSE) |
 | **Node** | `>= 22`（仅运行冒烟测试需要） |
@@ -76,7 +76,7 @@ Every path is built from this table — a caller selects an **id**, never a path
 | `rewind-snapshots` | `session-*` folders under `%USERPROFILE%\.dsh\rewind-snapshots` | aged, 30 days | caution | a recent session stays restorable |
 | `rotated-logs` | `*.old.log` and `*.log.N` files in the `logs` folders of the agent apps | aged, 3 days | safe | nothing reads a rotated file back |
 | `qoder-old-versions` | version folders under `%LOCALAPPDATA%\Programs\Qoder\.qoder-versions` other than the one the launcher names | purge | caution | the launcher's `state.ini` names the build it runs; an unreadable one means nothing is removed |
-| `orphan-app-data` | `%LOCALAPPDATA%\Tencent\QQGuild` - left by an app with no shortcut, no uninstall entry and nothing written for over two years | purge | caution | all four signals must agree before the folder is offered |
+| `orphan-app-data` | `%LOCALAPPDATA%\Tencent\QQGuild` - the QQGuild data folder | purge | caution | the whole folder is offered for deletion once no file in it has been written for 30 days |
 | `app-data-caches` | Chromium caches under `%LOCALAPPDATA%` for Electron, DingTalk, JianyingPro and the WeChat devtools | aged, 7 days | caution | an app that still runs rewrites its cache constantly, so only a week-old tree qualifies |
 | `office-update-cache` | `%LOCALAPPDATA%\Microsoft\Office\SolutionPackages` - update packages Office already applied | purge | caution | Office stages them before applying; nothing reads them back afterwards |
 
@@ -159,23 +159,31 @@ These are enforced in `lib/catalog.js` and must not be relaxed:
 - `editor-builds` drops a build only when `bin\code.cmd` exists and names a different build that is also on disk; `old_x` goes only while `x` is still beside it.
 - `database-backups` matches `.sqlite*.bak` by name only; the live `zotero.sqlite` is never a candidate.
 - `qoder-old-versions` reads the launcher's `state.ini` for the build it runs; a missing or unparsable file, or a named build that is not on disk, removes nothing.
-- `orphan-app-data` needs four independent signals to agree: no Start-menu shortcut, no uninstall entry, no folder under either `Program Files`, and no file written for two years. Any one missing and the folder is not offered.
+- `orphan-app-data` is offered when the QQGuild folder exists and no file in it has been written in the last 30 days; the whole folder is then a full-delete target. It does not check shortcuts, uninstall entries, or Program Files.
 - The directory Windows refuses to let an unelevated process write (`SoftwareDistribution\Download`) is labelled `elevation` and excluded from "reclaimable now". `C:\Windows\Temp` is **not** one of them on a default ACL: it grants `BUILTIN\Users` create and delete, so only EBUSY on a live file stops a delete there, which the age limit covers.
 
 ### Install
 
-Published on npm as [`dsh-disk-cleaner`](https://www.npmjs.com/package/dsh-disk-cleaner):
+A catalog entry has been submitted to the curated [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) list, which powers **dshmarket → Discover** ([PR #12970](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin/pull/12970), pending review) — once it merges, search **dsh-disk-cleaner** there and install it in one click. Until then, use a direct install below.
+
+Published on npm as [`dsh-disk-cleaner`](https://www.npmjs.com/package/dsh-disk-cleaner) — latest `1.6.2`:
 
 ```bash
 npm i dsh-disk-cleaner
 ```
 
+A prebuilt tarball is attached to the [v1.6.2 Release](https://github.com/stallenlu/dsh-disk-cleaner/releases/tag/v1.6.2); installing from it skips DSH's build-approval step:
+
+```bash
+dsh plugin --profile <profile> add https://github.com/stallenlu/dsh-disk-cleaner/releases/download/v1.6.2/dsh-disk-cleaner-1.6.2.tgz
+```
+
 Then enable it in the profile — in `$DSH_PROFILE_DIR/package.json`:
 
 ```json
 {
   "dependencies": {
-    "dsh-disk-cleaner": "^1.0.0"
+    "dsh-disk-cleaner": "^1.6.2"
   },
   "dsh": {
     "profile": {
@@ -196,7 +204,7 @@ The bundle's own `cordis.patch.yml` inserts the plugin row; no profile patch edi
 ### Development
 
 ```bash
-node smoke.mjs                       # 82 assertions, zero dependencies
+node smoke.mjs                       # 85 assertions, zero dependencies
 node --check lib/client.js           # and lib/index.js, lib/catalog.js, lib/audit.js, lib/plan.js
 ```
 
@@ -225,6 +233,8 @@ What the smoke test deliberately does **not** cover: anything that walks a real
 | A dry run reports what a real run frees | The 30-day rewind window reports 263 KB not 283 MB, and scan matches the dry run |
 | Grouping and folding | The real `groupRows` runs out of the bundle against a mixed list: fixed order, per-section totals, an unknown group lands in "other", an empty section is the folded one. A click on a section head folds that section and only that one, and a folded section's rows drop out of bulk select |
 | Visual layout | Checked by hand in the running Web UI. No browser automation here, so this one is a human check, not a test. |
+| Agent tool returns a string matching its output schema | `node smoke.mjs` regression assertion (the 1.6.1 fix) |
+| A real agent-tool delete invalidates the assessment cache | `node smoke.mjs` regression assertion (the 1.6.1 fix) |
 
 ### Implementation notes
 
@@ -248,20 +258,26 @@ What the smoke test deliberately does **not** cover: anything that walks a real
 ```
 ├─ package.json           dsh.bundle.patch + dsh.client { platform: "web" }
 ├─ cordis.patch.yml       - insert:  id: dsh-disk-cleaner
-├─ lib/index.js    (411)  Host: HTTP route + disk_cleaner tool, same run() for both; reveal
+├─ lib/index.js    (431)  Host: HTTP route + disk_cleaner tool, same run() for both; reveal
 ├─ lib/catalog.js  (1192)  The 32 targets, measurePath / purgePath / resolveTargets / drives
 ├─ lib/audit.js    (365)  Read-only assessment, 10-minute cache, areaPaths, exposes no deletion
 ├─ lib/plan.js     (150)  Pure: measurements → ordered steps
-├─ lib/client.js  (1492)  Client half: slots, panel, preferences, zh/en dictionaries, CSS
+├─ lib/client.js  (1493)  Client half: slots, panel, preferences, zh/en dictionaries, CSS
 ├─ locale/{en,zh}.json    Display metadata (meta.title / meta.description)
 ├─ icon.svg               Plugin icon
 ├─ README.md              This file
 ├─ LICENSE                MIT
-└─ smoke.mjs              82 assertions, zero dependencies
+└─ smoke.mjs              85 assertions, zero dependencies
 ```
 
 Client-half slots: `sidebar.panellist` (order 50, disposed in settings-only mode), `main` (keyed by the package name), `settings.section` (order 30, disposed in sidebar-only mode), `plugins.bundle.config` (keyed by the package name).
 
+### What's new
+
+- **1.6.2** — Documentation only: the README, the in-source comment, the panel's zh/en explanations and the tool's note legend now describe `orphan-app-data` as it actually behaves (the QQGuild folder is offered for full deletion once no file in it has been written for 30 days), instead of claiming four independent signals and a two-year idle period. No behaviour change; the refreshed README ships in the npm package and the [v1.6.2 Release](https://github.com/stallenlu/dsh-disk-cleaner/releases/tag/v1.6.2) tarball.
+- **1.6.1** — Fixed the `disk_cleaner` agent tool: `output.schema` now declares `type: 'string'`, matching the text `execute()` returns (previously every call was rejected by the host's output validator with `tool "disk_cleaner" returned invalid output: "value" must be an object`). A real delete through the agent tool now invalidates the assessment cache, the same way the panel's HTTP route does. Two regression assertions added; a prebuilt tarball ships on the [v1.6.1 Release](https://github.com/stallenlu/dsh-disk-cleaner/releases/tag/v1.6.1).
+- **1.6.0** — The 32 targets are grouped under seven foldable headings.
+
 ---
 
 <a id="中文"></a>
@@ -329,7 +345,7 @@ Client-half slots: `sidebar.panellist` (order 50, disposed in settings-only mode
 | `rewind-snapshots` | `%USERPROFILE%\.dsh\rewind-snapshots` 下的 `session-*` 目录 | 保留期 30 天 | 注意 | 最近的会话仍然可以回滚 |
 | `rotated-logs` | 各 agent 应用 `logs` 目录下的 `*.old.log` 与 `*.log.N` 文件 | 保留期 3 天 | 安全 | 轮转掉的日志不会被读回 |
 | `qoder-old-versions` | `%LOCALAPPDATA%\Programs\Qoder\.qoder-versions` 下不是启动器所指的那个版本目录 | 全清 | 注意 | 启动器 `state.ini` 写明它跑哪个版本；读不到就一个都不删 |
-| `orphan-app-data` | `%LOCALAPPDATA%\Tencent\QQGuild` —— 没有快捷方式、没有卸载项、两年多没写过文件的程序留下的数据 | 全清 | 注意 | 四条证据必须同时成立才会被列为可删 |
+| `orphan-app-data` | `%LOCALAPPDATA%\Tencent\QQGuild` —— QQ 频道数据目录 | 全清 | 注意 | 目录内 30 天没有任何文件写入时，整个目录会被列为全清目标 |
 | `app-data-caches` | `%LOCALAPPDATA%` 下 Electron、钉钉、剪映、微信开发者工具的 Chromium 缓存 | 保留期 7 天 | 注意 | 还在跑的程序会不停改写缓存，所以只有一周没动过的才算 |
 | `office-update-cache` | `%LOCALAPPDATA%\Microsoft\Office\SolutionPackages` —— Office 已应用的更新暂存包 | 全清 | 注意 | Office 先暂存再应用，应用后没有东西会读回 |
 
@@ -411,23 +427,31 @@ Client-half slots: `sidebar.panellist` (order 50, disposed in settings-only mode
 - `editor-builds` 只有在 `bin\code.cmd` 存在且指向另一份确实在磁盘上的构建时才删；`old_x` 也只有在 `x` 仍在旁边时才删。
 - `database-backups` 只按名字匹配 `.sqlite*.bak`，正在用的 `zotero.sqlite` 永不成为候选。
 - `qoder-old-versions` 从启动器的 `state.ini` 读出它实际运行哪个版本；文件缺失、解析不出、或它指的版本不在磁盘上，一律一个都不删。
-- `orphan-app-data` 要求四条独立证据同时成立：开始菜单没有快捷方式、注册表没有卸载项、两个 `Program Files` 下都没有目录、两年内没有任何文件被写过。缺一条就不会列为可删。
+- `orphan-app-data` 的判据只有一条：QQGuild 目录存在，且目录内 30 天内没有任何文件被写入过，此时整个目录被列为全清目标。它不检查快捷方式、卸载项或 Program Files。
 - 那个拒绝普通权限写入的 Windows 目录标为 `elevation`，并排除在「现在能回收」之外。
 
 ### 安装
 
-已发布到 npm：[`dsh-disk-cleaner`](https://www.npmjs.com/package/dsh-disk-cleaner)。
+已向精选目录 [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) 提交收录，它是 **dshmarket → 发现** 的数据源（[PR #12970](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin/pull/12970)，审核中）——合并后即可在 dshmarket 里搜索 **dsh-disk-cleaner** 一键安装。在那之前，用下面任一种直接安装方式。
+
+已发布到 npm：[`dsh-disk-cleaner`](https://www.npmjs.com/package/dsh-disk-cleaner)，最新版 `1.6.2`。
 
 ```bash
 npm i dsh-disk-cleaner
 ```
 
+[v1.6.2 Release](https://github.com/stallenlu/dsh-disk-cleaner/releases/tag/v1.6.2) 还附带一个预构建 tarball，从它安装可跳过 DSH 的构建授权步骤：
+
+```bash
+dsh plugin --profile <profile> add https://github.com/stallenlu/dsh-disk-cleaner/releases/download/v1.6.2/dsh-disk-cleaner-1.6.2.tgz
+```
+
 然后在 profile 里启用 —— 在 `$DSH_PROFILE_DIR/package.json`：
 
 ```json
 {
   "dependencies": {
-    "dsh-disk-cleaner": "^1.0.0"
+    "dsh-disk-cleaner": "^1.6.2"
   },
   "dsh": {
     "profile": {
@@ -445,14 +469,10 @@ git clone https://github.com/stallenlu/dsh-disk-cleaner
 
 bundle 自带的 `cordis.patch.yml` 会插入插件行，无需改 profile 的 patch。`link:` 依赖是符号链接，所以改 **client** 刷新页面即生效，改 **host**（`lib/index.js`）需要重新启用该 bundle 或重启 DSH。从 npm 装则是相反的一面：要升级就改版本号。
 
-```bash
-git clone https://github.com/stallenlu/dsh-disk-cleaner
-```
-
 ### 开发
 
 ```bash
-node smoke.mjs                       # 82 条断言，零依赖
+node smoke.mjs                       # 85 条断言，零依赖
 node --check lib/client.js           # 以及 lib/index.js、lib/catalog.js、lib/audit.js、lib/plan.js
 ```
 
@@ -481,6 +501,8 @@ node --check lib/client.js           # 以及 lib/index.js、lib/catalog.js、li
 | 预演报告的字节数等于真删能释放的字节数 | 30 天的回滚窗口报 263 KB 而不是 283 MB，且扫描结果与预演一致 |
 | 分类与折叠 | 从 bundle 里取出真正的 `groupRows` 跑一组混合数据：顺序固定、按类合计、未知类别落到「其他」、空的类别是收起来的那个。点某一类的标题只折叠这一类，折叠里的行不参与批量选择 |
 | 视觉排版 | 在运行中的 Web UI 里手工确认过。本环境没有浏览器自动化，所以这条是人眼检查，不是测试。 |
+| agent 工具返回字符串且与 output.schema 一致 | `node smoke.mjs` 回归断言（1.6.1 修复） |
+| agent 工具真删后评估缓存失效 | `node smoke.mjs` 回归断言（1.6.1 修复） |
 
 ### 实现要点
 
@@ -504,20 +526,26 @@ node --check lib/client.js           # 以及 lib/index.js、lib/catalog.js、li
 ```
 ├─ package.json           dsh.bundle.patch + dsh.client { platform: "web" }
 ├─ cordis.patch.yml       - insert:  id: dsh-disk-cleaner
-├─ lib/index.js    (411)  Host：HTTP 路由 + disk_cleaner 工具，共用同一个 run()，含 reveal
+├─ lib/index.js    (431)  Host：HTTP 路由 + disk_cleaner 工具，共用同一个 run()，含 reveal
 ├─ lib/catalog.js  (1192)  32 个目标，measurePath / purgePath / resolveTargets / drives
 ├─ lib/audit.js    (365)  只读评估，10 分钟缓存，带 areaPaths，不暴露任何删除
 ├─ lib/plan.js     (150)  纯函数：测量结果 → 有序步骤
-├─ lib/client.js  (1492)  Client 半面：slot、面板、偏好、zh/en 字典、CSS
+├─ lib/client.js  (1493)  Client 半面：slot、面板、偏好、zh/en 字典、CSS
 ├─ locale/{en,zh}.json    展示元数据（meta.title / meta.description）
 ├─ icon.svg               插件图标
 ├─ README.md              本文件
 ├─ LICENSE                MIT
-└─ smoke.mjs              82 条断言，零依赖
+└─ smoke.mjs              85 条断言，零依赖
 ```
 
 Client 半面注册的 slot：`sidebar.panellist`（order 50，仅设置页模式下拆除）、`main`（以包名为 key）、`settings.section`（order 30，仅侧边栏模式下拆除）、`plugins.bundle.config`（以包名为 key）。
 
+### 更新记录
+
+- **1.6.2** — 仅文档修正：README、源码注释、面板中英文说明和工具里的注意码释义，现在都按真实行为描述 `orphan-app-data`（QQGuild 目录内 30 天没有文件写入时会被整目录列为可全清），不再声称「四条独立证据 / 两年未写」。行为不变；更新后的 README 也随 npm 包与 [v1.6.2 Release](https://github.com/stallenlu/dsh-disk-cleaner/releases/tag/v1.6.2) 的 tarball 一起发布。
+- **1.6.1** — 修复了 `disk_cleaner` agent 工具：`output.schema` 现在声明 `type: 'string'`，与 `execute()` 返回的文本一致（此前每次调用都被宿主的输出校验器拒绝，报 `tool "disk_cleaner" returned invalid output: "value" must be an object`）。经由 agent 工具真删后也会让评估缓存失效，与面板的 HTTP 路径一致。新增两条回归断言；[v1.6.1 Release](https://github.com/stallenlu/dsh-disk-cleaner/releases/tag/v1.6.1) 附带预构建 tarball。
+- **1.6.0** — 32 个目标按七个可折叠分组归类。
+
 ## License
 
 [MIT](LICENSE)

package/lib/catalog.js

@@ -872,9 +872,9 @@ const CATALOG = [
     roots: ['LOCALAPPDATA'],
     paths: () => {
       const guild = path.join(env('LOCALAPPDATA') ?? '', 'Tencent', 'QQGuild');
-      // Measured: no Start-menu shortcut, no uninstall entry, no Program Files folder and no
-      // file touched for over two years. The folder also carries its own `Uninstall QQGuild.exe`,
-      // which only a real install does. Every one of those signals has to agree before it goes.
+      // The QQGuild data folder is offered for full deletion when it exists and no file
+      // inside it has been written in the last 30 days. Nothing else is checked - no
+      // shortcut, uninstall entry or Program Files probe. Keep the docs in step with this.
       const recent = newestMtime(guild) > Date.now() - 30 * DAY;
       return isDir(guild) && !recent ? [guild] : [];
     },

package/lib/client.js

@@ -41,7 +41,7 @@ window.__ModuleLoader__.load({
       'why_pending-update': '只清 {n} 天前的下载，避免删掉还没装的更新',
       why_rollback: '每个插件/程序只留版本号最高的一份，其余是回滚副本',
       why_superseded: '版本号不高于已装版本的更新包，装着的那份已经生效',
-      why_orphan: '写这个目录的程序已经不在这台机器上了：没有快捷方式、没有卸载项，两年多没写过文件',
+      why_orphan: 'QQ 频道数据目录：目录内 30 天没有任何文件写入时会被整目录清除',
       why_history: '每个会话的整文件备份，删了不影响会话本身',
       why_duplicate: '内容完全相同的重复副本，保留最新那份',
       'why_database-backup': '升级前的数据库副本，正在用的数据库还在旁边',
@@ -213,7 +213,7 @@ window.__ModuleLoader__.load({
       'why_pending-update': 'only downloads older than {n} day(s), so a pending update survives',
       why_rollback: 'only the highest version of each family stays; the rest are rollback copies',
       why_superseded: 'the update package version is not above what is installed, so it is already applied',
-      why_orphan: 'the app that wrote this folder is gone: no shortcut, no uninstall entry, nothing written for over two years',
+      why_orphan: 'the QQGuild data folder, deleted in full when no file in it has been written for 30 days',
       why_history: 'a whole-file backup per session; removing it does not touch the session',
       why_duplicate: 'an identical copy; the newest one is kept',
       'why_database-backup': 'a copy made before an upgrade; the live database is beside it',

package/lib/index.js

@@ -210,7 +210,7 @@ const NOTE_MEANING = {
   history: 'a backup snapshot of file edits that nothing reads back; the live state sits beside it',
   duplicate: 'a byte-identical copy of a directory that is still present',
   'database-backup': 'a copy of a database file taken before an upgrade; the live database is beside it',
-  orphan: 'the app that wrote this folder is no longer installed: no shortcut, no uninstall entry, and nothing written for over two years',
+  orphan: 'the QQGuild data folder is deleted in full when no file in it has been written for 30 days',
 };
 
 const formatBytes = (bytes) => {
@@ -349,7 +349,7 @@ export function apply(ctx) {
           additionalProperties: false,
         },
         output: {
-          schema: { type: 'object', additionalProperties: true },
+          schema: { type: 'string' },
           render: (args, value) => [{ type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) }],
         },
         timeoutMs: 300_000,
@@ -413,6 +413,7 @@ export function apply(ctx) {
             if (ids === undefined || ids.length === 0) throw new Error('clean needs at least one target id');
             const dryRun = args.confirm !== true;
             const results = await clean(ids, { dryRun, drive: readDrive(args.drive) });
+            if (!dryRun) invalidateAudit();
             const freed = results.reduce((sum, item) => sum + item.bytes, 0);
             const files = results.reduce((sum, item) => sum + item.removed, 0);
             const failed = results.reduce((sum, item) => sum + item.failed, 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-disk-cleaner",
-  "version": "1.6.0",
+  "version": "1.6.2",
   "type": "module",
   "description": "Disk Cleaner for DSH: scan known-safe cache locations, see what they occupy, and reclaim the space from a panel or from the agent.",
   "keywords": [

package/smoke.mjs

@@ -260,6 +260,11 @@ check(
 check('tool needs no id for overview', JSON.stringify(definition.parameters.required) === JSON.stringify(['action']));
 check('tool description warns audit is read-only', /read-only: it never removes anything/.test(definition.description));
 check('every effect is labelled', applied.every((label) => typeof label === 'string' && label.startsWith('dsh-disk-cleaner:')));
+check('tool output schema matches its string reply', definition.output.schema.type === 'string' && typeof (await definition.execute({ action: 'overview' })) === 'string');
+check('the read-only agent clean keeps the audit cache in sync', /if \(!dryRun\) invalidateAudit\(\);[\s\S]*const freed = results\.reduce/.test(index));
+check('orphan target descriptions state the real 30-day rule, not four signals / two years',
+  /30 days/.test(catalog) && /30 days/.test(index) && /QQGuild data folder/.test(source) &&
+  !/four independent signals|over two years|no Start-menu shortcut|two years/.test(catalog + index + source));
 
 const ids = [...catalog.matchAll(/^\s{4}id: '([a-z-]+)',$/gm)].map((m) => m[1]);
 check('catalog has the documented 32 targets', ids.length === 32, `got ${ids.length}`);