@mison/wecom-cleaner 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mison
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,323 @@
+# wecom-cleaner
+
+<p align="left">
+  <a href="https://www.npmjs.com/package/@mison/wecom-cleaner"><img alt="npm" src="https://img.shields.io/npm/v/%40mison%2Fwecom-cleaner?style=flat-square" /></a>
+  <a href="./LICENSE"><img alt="license" src="https://img.shields.io/badge/license-MIT-2ea043?style=flat-square" /></a>
+  <img alt="node" src="https://img.shields.io/badge/node-%3E%3D20-1f6feb?style=flat-square" />
+  <img alt="platform" src="https://img.shields.io/badge/platform-macOS-0ea5e9?style=flat-square" />
+  <img alt="engine" src="https://img.shields.io/badge/engine-Node%20%2B%20Zig-0891b2?style=flat-square" />
+</p>
+
+企业微信本地缓存清理工具（交互式 CLI/TUI）。
+
+- 软件名：`wecom-cleaner`
+- npm 包：`@mison/wecom-cleaner`
+- 命令名：`wecom-cleaner`
+- 仓库：<https://github.com/MisonL/wecom-cleaner>
+
+> 定位：在“可回收、可恢复、可审计”前提下，清理企业微信本地缓存，避免误删业务资料。
+
+## 目录
+
+- [项目定位](#项目定位)
+- [功能总览](#功能总览)
+- [能力边界](#能力边界)
+- [安装与运行](#安装与运行)
+- [常用参数](#常用参数)
+- [数据与审计文件](#数据与审计文件)
+- [开发与质量门禁](#开发与质量门禁)
+- [发布与打包](#发布与打包)
+- [FAQ](#faq)
+
+## 项目定位
+
+`wecom-cleaner` 解决的是“本地缓存空间治理”问题，不改变服务端数据。
+
+设计原则：
+
+- 安全优先：默认以回收区搬移代替直接删除。
+- 可恢复：所有可执行删除都记录索引并支持按批次恢复。
+- 可审计：关键分支会写入状态码，便于追踪与复盘。
+- 渐进增强：有 Zig 核心则加速，无则自动回退 Node。
+
+## 功能总览
+
+| 模块               | 是否可执行删除 | 说明                                               |
+| ------------------ | -------------- | -------------------------------------------------- |
+| 年月清理（默认）   | 是             | 按账号 + 年月 + 类型筛选缓存，支持 dry-run。       |
+| 会话分析           | 否             | 只读分析目录/体积分布，不做删除。                  |
+| 全量空间治理       | 是             | 分级治理高占用缓存目录（安全层/谨慎层/受保护层）。 |
+| 回收区治理         | 是             | 按保留策略清理回收区历史批次，支持 dry-run。       |
+| 恢复已删除批次     | 是             | 基于索引恢复，支持覆盖/重命名/跳过。               |
+| 系统自检（doctor） | 否             | 检查目录权限、账号发现、核心可用性与回收区健康。   |
+| 交互配置           | 否             | 配置根目录、主题、文件存储目录、外部自动探测等。   |
+
+### 关键能力
+
+1. 多账号支持
+
+- 自动识别 `Profiles` 下账号目录。
+- 账号以 `用户名 | 企业名 | 短ID` 显示，可多选。
+- 支持账号别名，修正常见不可读字段。
+
+2. 文件存储目录识别
+
+- 支持默认路径、手动配置路径、自动探测路径。
+- 自动探测采用结构匹配（如 `*/WXWork Files/Caches`），不依赖目录名。
+- 自动探测结果默认不预选，需用户确认后纳入处理。
+
+3. 删除与恢复链路
+
+- 删除动作统一进入程序回收区，而不是直接 `rm`。
+- 写入 `index.jsonl` 审计记录，恢复按批次回放。
+- 恢复时做路径边界校验（含 `realpath` 防符号链接越界）。
+- 恢复支持先 `dry-run` 预演，再选择是否执行真实恢复。
+
+4. 回收区保留策略
+
+- 支持“保留最近 N 批 + 保留近 N 天 + 容量阈值”联合治理。
+- 超过阈值会给出空间提示，可一键进入回收区治理。
+
+5. Zig 核心与自动修复
+
+- 有可用 Zig 核心时自动启用加速。
+- 不可用时自动回退 Node，功能不受影响。
+- 可按 manifest 下载并校验 SHA256 后修复核心。
+
+6. 可观测性与并发安全
+
+- `doctor` 模式可输出人类可读报告，或通过 `--json` 输出结构化结果。
+- `doctor` 模式为只读体检：不会自动创建状态目录/回收区，也不会触发 Zig 自动修复下载。
+- 多实例并发默认加锁，检测到陈旧锁可交互清理或通过 `--force` 自动清理。
+
+## 能力边界
+
+企业微信会话数据库为私有/加密格式，当前无法稳定建立“会话名 -> 本地缓存目录”的强映射。
+
+因此：
+
+- 支持按“年月目录”执行清理。
+- 支持按“会话维度”做只读分析。
+- 不提供“按会话自动删除”。
+
+## 安装与运行
+
+### 方式一：直接运行
+
+```bash
+npx @mison/wecom-cleaner
+```
+
+### 方式二：本地开发
+
+```bash
+npm install
+npm run build:native
+npm run dev
+```
+
+### 全菜单 smoke 回归
+
+```bash
+npm run e2e:smoke
+```
+
+说明：
+
+- 脚本会在 `/tmp/wecom-e2e-*` 构造隔离夹具，不触碰真实企业微信目录。
+- 覆盖开始菜单与关键分支：年月清理、会话分析、全量治理、回收区治理、恢复、系统自检、设置。
+- 可用 `npm run e2e:smoke -- --keep` 保留日志与测试目录。
+
+## 常用参数
+
+```bash
+wecom-cleaner --root ~/Library/Containers/com.tencent.WeWorkMac/Data/Documents/Profiles
+wecom-cleaner --state-root ~/.wecom-cleaner-state
+wecom-cleaner --external-storage-root /Volumes/Data/MyWeComStorage
+wecom-cleaner --external-storage-auto-detect false
+wecom-cleaner --dry-run-default true
+wecom-cleaner --mode cleanup_monthly
+wecom-cleaner --mode space_governance
+wecom-cleaner --mode recycle_maintain
+wecom-cleaner --mode doctor
+wecom-cleaner --theme auto
+wecom-cleaner --json
+wecom-cleaner --force
+```
+
+### `--mode` 可选值
+
+- `cleanup_monthly`
+- `analysis_only`
+- `space_governance`
+- `recycle_maintain`
+- `restore`
+- `doctor`
+- `settings`
+
+### `--theme` 可选值
+
+- `auto`：自动判断终端主题
+- `light`：亮色
+- `dark`：暗色
+
+### 额外环境变量
+
+- `WECOM_CLEANER_NATIVE_AUTO_REPAIR=true|false`：Zig 自动修复总开关（默认 `true`）
+- `WECOM_CLEANER_NATIVE_BASE_URL=<url>`：核心下载基地址
+- `WECOM_CLEANER_NATIVE_DOWNLOAD_TIMEOUT_MS=<ms>`：下载超时（默认 `15000`）
+- `WECOM_CLEANER_NATIVE_PROBE_TIMEOUT_MS=<ms>`：核心探针超时（默认 `3000`，最小 `500`）
+- `WECOM_CLEANER_EXTERNAL_AUTO_DETECT=true|false`：外部存储自动探测总开关
+
+## 数据与审计文件
+
+默认状态目录：`~/.wecom-cleaner-state`
+
+- `config.json`：交互配置
+- `account-aliases.json`：账号别名
+- `index.jsonl`：删除/恢复流水审计
+- `recycle-bin/`：回收区
+- `.wecom-cleaner.lock`：运行锁文件（防并发误操作）
+
+`index.jsonl` 常见字段：
+
+- `scope`：`cleanup_monthly` 或 `space_governance`
+- `tier`：`safe` / `caution` / `protected`
+- `status`：`success`、`dry_run`、`skipped_*`、`failed`
+- `error_type`：错误分类（如 `path_not_found`、`path_validation_failed`、`permission_denied`）
+
+回收区治理审计（`action=recycle_maintain`）常见字段：
+
+- `selected_by_age`：按年龄规则选中的批次数
+- `selected_by_size`：按容量规则补选的批次数
+- `remaining_bytes`：治理后回收区总占用
+
+常见越界拦截原因（`skipped_invalid_path.invalid_reason`）：
+
+- `source_outside_profile_root`
+- `source_outside_governance_root`
+- `source_symlink_escape`
+- `recycle_symlink_escape`
+- `missing_allowed_root`
+- `missing_recycle_root`
+- `source_path_unresolvable`
+- `recycle_path_unresolvable`
+
+## 开发与质量门禁
+
+```bash
+# 语法检查
+npm run check
+
+# 单元测试
+npm run test
+
+# 覆盖率报告
+npm run test:coverage
+
+# 覆盖率门禁（lines/statements >= 75%，functions >= 80%，branches >= 60%）
+npm run test:coverage:check
+
+# 格式化与风格检查
+npm run format
+npm run format:check
+```
+
+发布前推荐全量门禁：
+
+```bash
+npm run check
+npm run test:coverage:check
+npm run format:check
+npm run e2e:smoke -- --keep
+npm run pack:tgz:dry-run
+```
+
+当前基线（`v1.0.0`）：
+
+- 单元测试：`47/47` 通过。
+- 覆盖率：`statements 85.65%`，`branches 70.99%`，`functions 91.39%`，`lines 85.65%`。
+- 全菜单 smoke：通过（含恢复冲突分支与 doctor JSON 分支）。
+
+## 发布与打包
+
+`prepack` 会自动执行：
+
+- `npm run build:native:release`
+- `npm run check`
+
+默认构建两个 macOS 核心：
+
+- `native/bin/darwin-x64/wecom-cleaner-core`
+- `native/bin/darwin-arm64/wecom-cleaner-core`
+
+本地交付包（无作用域前缀）建议：
+
+```bash
+npm run pack:tgz
+```
+
+输出示例：`wecom-cleaner-<version>.tgz`
+
+### 正式发布（GitHub Release + npm）
+
+```bash
+# 1) 发布前检查
+npm run check
+npm run test:coverage:check
+npm run format:check
+npm run e2e:smoke
+npm run pack:tgz
+
+# 2) 推送主分支与标签
+git push origin main
+git tag v1.0.0
+git push origin v1.0.0
+
+# 3) 发布 GitHub Release（附 tgz 包）
+gh release create v1.0.0 \
+  --title "v1.0.0" \
+  --notes-file docs/releases/v1.0.0.md \
+  wecom-cleaner-1.0.0.tgz
+
+# 4) 发布 npm
+npm publish --access public
+```
+
+建议发布前确认登录状态：
+
+- `gh auth status`
+- `npm whoami`
+
+跨平台构建示例：
+
+```bash
+# 按当前机器平台
+./native/zig/build.sh
+
+# 发布前构建 macOS 双架构
+npm run build:native:release
+
+# 指定目标编译（示例）
+TARGET_OS=darwin TARGET_ARCH=arm64 ./native/zig/build.sh
+TARGET_OS=windows TARGET_ARCH=x64 ./native/zig/build.sh
+```
+
+## FAQ
+
+### 1) “Zig加速:已就绪” 和 “已生效” 有什么区别？
+
+- 已就绪：检测到 Zig 核心，但当前仅在菜单阶段，还没进入扫描。
+- 已生效：已经进入扫描，且本次实际使用 Zig。
+
+### 2) 为什么显示 “Node回退”？
+
+检测到 Zig 核心，但本次运行探针失败或运行异常，已自动切回 Node，功能可继续使用。
+
+### 3) 会不会误删企业文档？
+
+默认策略不会把普通业务文档目录（例如 `WeDrive/<企业名>/...`）纳入治理规则；执行前还有分级提示、确认和回收区兜底。
+
+---
+
+如果你希望我提供“按你当前机器目录结构定制的一键安全清理方案”，可以直接给我一份 `--dry-run` 输出。

package/docs/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,162 @@
+# wecom-cleaner 实施与现状说明
+
+## 1. 产品定位
+
+`wecom-cleaner` 是企业微信本地缓存治理工具，核心目标是“可安全回收空间、可审计、可恢复”。
+
+- 软件名：`wecom-cleaner`
+- npm 包名：`@mison/wecom-cleaner`
+- 命令名：`wecom-cleaner`
+
+## 2. 当前功能范围
+
+1. 开始菜单
+
+- 年月清理（默认，可执行删除）
+- 会话分析（只读）
+- 全量空间治理（分级治理）
+- 回收区治理（保留策略）
+- 恢复已删除批次
+- 系统自检（doctor）
+- 交互配置
+
+2. 年月清理
+
+- 多账号选择与别名管理。
+- 按截止年月或手动勾选月份筛选。
+- 按缓存类型筛选，`wwsecurity` 默认不勾选。
+- 删除动作统一进入回收区，不直接 `rm`。
+
+3. 会话分析（只读）
+
+- 统计账号/类型/月份维度占用。
+- 明确能力边界：不支持按“会话名”自动删除。
+
+4. 全量空间治理
+
+- 对 `Profiles` 外高占用目录进行分层治理（安全层/谨慎层/受保护层）。
+- 谨慎层二次确认，受保护层仅分析不删除。
+- 支持外部文件存储缓存目录（`WXWork Files/Caches`）纳入治理。
+
+5. 恢复
+
+- 支持按批次恢复。
+- 冲突策略：覆盖 / 重命名 / 跳过。
+- 支持先 dry-run 预演，再确认真实恢复。
+- 恢复路径使用 `realpath` 做越界校验并写审计记录。
+
+6. 回收区治理
+
+- 支持“保留最近 N 批 + 保留近 N 天 + 容量阈值”联合治理。
+- 支持 dry-run 预览与真实清理。
+- 审计记录 `action=recycle_maintain`，包含按年龄/按容量选中的批次数。
+
+7. 系统自检（doctor）
+
+- 检查 Profile 根目录、状态目录、回收区与索引目录权限。
+- 检查账号发现、文件存储目录识别结果。
+- 检查 native manifest/随包核心/缓存核心探针状态。
+- 检查回收区容量健康并输出建议。
+
+## 3. 技术架构
+
+1. CLI 主体
+
+- `src/cli.js`：交互流程编排。
+- `src/config.js`：CLI 参数与配置持久化。
+
+2. 领域模块
+
+- `src/scanner.js`：账号发现、目录扫描、体积计算。
+- `src/cleanup.js`：删除（迁移到回收区）与索引记录。
+- `src/restore.js`：批次恢复与冲突处理。
+- `src/analysis.js`：只读分析输出。
+- `src/recycle-maintenance.js`：回收区保留策略与治理执行。
+- `src/doctor.js`：系统自检报告生成。
+- `src/error-taxonomy.js`：错误分类与展示标签。
+- `src/lock.js`：单实例运行锁（含陈旧锁处理）。
+
+3. 引擎层
+
+- `src/native-bridge.js`：Zig 核心探测、校验、自动修复下载、Node 回退。
+- `native/manifest.json`：核心下载清单与 `SHA256`。
+
+## 4. 安全与审计策略
+
+1. 删除安全
+
+- 所有删除先进入 `recycle-bin/`。
+- 每条动作写入 `index.jsonl`。
+
+2. 恢复安全
+
+- 严格限制恢复源与目标必须位于允许根路径。
+- 对软链接逃逸与路径不可解析场景做拒绝与审计。
+- 恢复 dry-run 与真实恢复均写审计状态，便于先演练后执行。
+
+3. 并发安全
+
+- 非 doctor 模式默认启用运行锁，避免多实例并发操作同一状态目录。
+- 支持识别陈旧锁并按 `--force` 自动清理重试。
+
+3. Zig 自动修复安全
+
+- 仅按清单下载固定目标。
+- 下载后先做 `SHA256` 校验，再做 `--ping` 探针。
+- 校验失败或探针失败会删除缓存并回退 Node。
+
+## 5. 质量保障与门禁
+
+1. 代码风格
+
+- 统一使用 Prettier（仓库内置 `.prettierrc.json`）。
+- 执行命令：`npm run format` / `npm run format:check`。
+
+2. 单元测试
+
+- 使用 Node 原生测试框架（`node:test`）。
+- 覆盖核心模块：`config/utils/cleanup/restore/scanner/native-bridge/analysis`。
+
+3. 覆盖率
+
+- 使用 `c8` 输出覆盖率报告。
+- 门禁阈值：`lines/statements >= 75%`，`functions >= 80%`，`branches >= 60%`。
+- 命令：`npm run test:coverage` / `npm run test:coverage:check`。
+- `v1.0.0` 基线：`statements 85.65%`，`branches 70.99%`，`functions 91.39%`，`lines 85.65%`。
+
+4. 端到端回归
+
+- 使用 `scripts/e2e-smoke.sh` 覆盖全部一级菜单与关键分支（含 doctor 与回收区治理）。
+
+## 6. 推荐发布前检查
+
+```bash
+npm run check
+npm run test:coverage:check
+npm run format:check
+npm run e2e:smoke -- --keep
+npm run pack:tgz:dry-run
+```
+
+## 7. 发布执行（首个正式版）
+
+1. 版本与产物
+
+- `package.json` / `package-lock.json`：`1.0.0`
+- `native/manifest.json`：版本与 `baseUrl` 对齐 `v1.0.0`
+- 默认打包双架构核心：`darwin-x64` + `darwin-arm64`
+
+2. GitHub Release
+
+```bash
+git push origin main
+git tag v1.0.0
+git push origin v1.0.0
+gh release create v1.0.0 --title "v1.0.0" --notes-file docs/releases/v1.0.0.md wecom-cleaner-1.0.0.tgz
+```
+
+3. npm 发布
+
+```bash
+npm publish --access public
+```

package/docs/releases/v1.0.0.md

@@ -0,0 +1,32 @@
+# wecom-cleaner v1.0.0
+
+首个正式版本，聚焦“安全、可恢复、可审计”的企业微信本地缓存治理。
+
+## 主要能力
+
+- 年月清理（默认可执行删除，支持 dry-run）
+- 会话分析（只读）
+- 全量空间治理（分级策略）
+- 回收区治理（保留策略 + dry-run）
+- 批次恢复（覆盖/重命名/跳过）
+- 系统自检 doctor（支持 `--json`）
+
+## 本次重点改进
+
+- 修复恢复 `dry-run` 分支潜在实删风险，预演不再改动源目录。
+- 回收区治理增加批次路径边界校验，防止异常索引导致越界删除。
+- doctor 改为只读体检：不创建目录、不触发自动修复下载。
+- Zig 核心探针增加超时控制，避免异常阻塞。
+- 外部存储根目录推断增强：`Documents/Profiles` 大小写不敏感。
+- e2e smoke 清理逻辑加固，避免误删非安全路径。
+
+## 质量与验证
+
+- 单元测试：47/47 通过
+- 覆盖率：statements 85.65%，branches 70.99%，functions 91.39%，lines 85.65%
+- 全菜单 smoke：通过（含恢复冲突分支、doctor JSON 分支）
+
+## 兼容性
+
+- 当前正式支持：macOS（x64 / arm64）
+- Windows 兼容在后续版本规划中

package/native/README.md

@@ -0,0 +1,9 @@
+# Zig 核心说明
+
+当前版本采用 `Node CLI + Zig 核心预留` 架构：
+
+- 如果存在 `native/bin/<platform>-<arch>/wecom-cleaner-core`，CLI 会尝试加载 Zig 核心。
+- 如果未检测到 Zig 二进制，会自动回退到 Node 引擎，不影响使用。
+- 自动修复下载使用 `native/manifest.json` 固定版本清单，并执行 `SHA256` 强校验 + `--ping` 探针校验。
+
+后续可将高并发目录扫描、体积计算、索引操作迁移到 Zig，以提升性能和可维护性。

package/native/manifest.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "version": "1.0.0",
+  "baseUrl": "https://raw.githubusercontent.com/MisonL/wecom-cleaner/v1.0.0/native/bin",
+  "targets": {
+    "darwin-x64": {
+      "binaryName": "wecom-cleaner-core",
+      "sha256": "14cfa26895101e7b71824e6bb9282f08a38f9dad72d4df2934094eb2ceefbad0"
+    },
+    "darwin-arm64": {
+      "binaryName": "wecom-cleaner-core",
+      "sha256": "fc33ce3fb44309170da8c2867d11eae552e2e9d3c95b8f0e5a8e8392bb630744"
+    }
+  }
+}

package/native/zig/build.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
+
+HOST_OS="$(uname -s | tr '[:upper:]' '[:lower:]')"
+HOST_ARCH="$(uname -m)"
+
+RAW_OS="${TARGET_OS:-$HOST_OS}"
+RAW_ARCH="${TARGET_ARCH:-$HOST_ARCH}"
+
+case "$RAW_OS" in
+  darwin|macos)
+    OS_TAG="darwin"
+    ZIG_OS="macos"
+    ;;
+  linux)
+    OS_TAG="linux"
+    ZIG_OS="linux"
+    ;;
+  windows|windows_nt|mingw*|msys*|cygwin*)
+    OS_TAG="windows"
+    ZIG_OS="windows"
+    ;;
+  *)
+    echo "不支持的操作系统: $RAW_OS" >&2
+    exit 1
+    ;;
+esac
+
+case "$RAW_ARCH" in
+  x86_64|amd64|x64)
+    ARCH_TAG="x64"
+    ZIG_ARCH="x86_64"
+    ;;
+  arm64|aarch64)
+    ARCH_TAG="arm64"
+    ZIG_ARCH="aarch64"
+    ;;
+  *)
+    echo "不支持的架构: $RAW_ARCH" >&2
+    exit 1
+    ;;
+esac
+
+OUT_DIR="$ROOT_DIR/native/bin/${OS_TAG}-${ARCH_TAG}"
+mkdir -p "$OUT_DIR"
+
+BIN_NAME="wecom-cleaner-core"
+if [[ "$OS_TAG" == "windows" ]]; then
+  BIN_NAME="${BIN_NAME}.exe"
+fi
+
+declare -a BUILD_CMD
+BUILD_CMD=(
+  zig build-exe "$ROOT_DIR/native/zig/src/main.zig"
+  -O ReleaseFast
+  -fstrip
+  -femit-bin="$OUT_DIR/$BIN_NAME"
+)
+
+if [[ -n "${TARGET_OS:-}" || -n "${TARGET_ARCH:-}" ]]; then
+  BUILD_CMD+=(-target "${ZIG_ARCH}-${ZIG_OS}")
+fi
+
+"${BUILD_CMD[@]}"
+
+echo "构建完成: $OUT_DIR/$BIN_NAME"