dsh-rewind-plugin 0.4.2 → 0.5.0

package/docs/{release.md → release/release.zh.md}

@@ -1,53 +1,7 @@
-# Release
-
-## First release (manual, one-time)
-
-Trusted Publisher can only be configured once the package exists, so the first
-version is published locally:
-
-```sh
-npm login
-npm publish --access public
-```
-
-- If prompted for `EOTP`: complete the browser auth link the CLI prints, or
-  retry with a 6-digit code — `npm publish --otp=<code>`.
-- The first version carries no provenance (local path) — acceptable; every CI
-  release after that publishes with Sigstore/SLSA provenance automatically.
-
-## Configure Trusted Publisher (npmjs.com, one-time)
-
-Open `https://www.npmjs.com/package/dsh-rewind-plugin` → package **settings** →
-**Trusted Publisher**:
-
-| Field | Value |
-| --- | --- |
-| Provider | GitHub Actions |
-| Organization or user | `SiriLee` |
-| Repository | `dsh-rewind` (the GitHub repo, not the npm name) |
-| Workflow filename | `publish.yml` |
-| Environment | empty |
-| Allowed actions | `npm publish` |
-
-## Subsequent releases (CI, automatic)
-
-```sh
-npm version patch
-git push origin main --tags   # triggers .github/workflows/publish.yml
-```
-
-- The workflow verifies the tag matches `package.json`, runs typecheck + tests +
-  a full build + artifact verification, publishes with `--provenance`
-  (Sigstore), and creates a GitHub Release. It is **idempotent** — an already
-  published version is skipped.
-- CI (`.github/workflows/ci.yml`) runs the same checks on every push / PR, plus
-  a `npm pack --dry-run` sanity check that the tarball carries `lib/` and
-  `LICENSE`.
-
----
-
 # 发布流程
 
+[English](release.md)
+
 ## 首次发布（手动，一次性）
 
 Trusted Publisher 要求**包已存在**才能配置，因此首个版本走本地发布：
@@ -86,8 +40,9 @@ git push origin main --tags   # 触发 .github/workflows/publish.yml
 - workflow 校验 tag 与 `package.json` 版本一致，跑 typecheck + 测试 + 完整
   构建 + 产物验证，以 `--provenance`（Sigstore）发布并创建 GitHub Release。
   **幂等**——已发布的版本会跳过。
-- CI（`.github/workflows/ci.yml`）在每次 push / PR 跑相同检查，外加
-  `npm pack --dry-run` 校验 tarball 含 `lib/` 与 `LICENSE`。
+- CI（`.github/workflows/ci.yml`）在每次 push / PR 跑 `npm run check`——
+  typecheck + 测试 + 构建 + 产物验证 + `npm pack --dry-run`，且覆盖
+  engines 两个边界版本；tarball 布局由 `tests/package-layout.test.ts` 守护。
 
 ## DSH 版本适配（peer 范围维护）
 
@@ -102,7 +57,6 @@ OR 并集覆盖 DSH 已发布的每个 rc 元组系列（如 `^0.1.0-rc.6 || ^0.
 - **自动检测**：`node scripts/check-dsh-version.mjs` 对比 npm 最新版本与
   peer 覆盖的元组，输出是否需追加（exit 0 无需动作，exit 1 需要）。
 - **更新步骤**：给每个 `@deepseek-ai/dsh-*` peer 追加 `|| ^<新元组>-rc.<n>`
-  → devDependencies 同步升到最新 → `npm install` → `npm run typecheck` /
-  `npm test` / `npm run verify:host` → 发版。
+  → devDependencies 同步升到最新 → `npm install` → `npm run check` → 发版。
 - **正式版后收敛**：DSH 发布 final 版本后，正式版不受 prerelease 元组规则
   限制，peer 可收敛为稳定的 `^0.1.x` 单范围，此节即可删除。

package/docs/snapshot-auto-cleanup.md

@@ -0,0 +1,71 @@
+# Snapshot auto-cleanup
+
+The rewind store writes one on-disk `before` backup per tracked file change,
+grouped by its anchor message. Snapshots are deduped within a session and capped
+at the newest 100 anchor groups, but across sessions that are no longer active
+the store can
+still grow without bound. `snapshot-auto-cleanup` is an OPTIONAL global policy
+(off by default) that removes the whole snapshot directory of a session that has
+been **long-inactive** — untouched past a configurable idle cutoff.
+
+It only ever removes the whole snapshot **directory** of a long-inactive session.
+It never touches the active session's snapshots, never touches the conversation
+log, and leaves snapshot data within the idle cutoff alone.
+
+## Commands
+
+```
+/snapshot-auto-cleanup                  show status (enabled, max-age, config path)
+/snapshot-auto-cleanup on|off           enable/disable the automatic sweep
+/snapshot-auto-cleanup max-age <days>   set the idle cutoff (positive integer)
+/snapshot-auto-cleanup run              dry-run: list what would be removed
+/snapshot-auto-cleanup run --apply      actually remove those sessions
+```
+
+`run` is a manual escape hatch and works whether or not the automatic cleanup is
+`on`. `run` defaults to a dry-run; add `--apply` to execute.
+
+## Config file
+
+The policy is persisted to `~/.dsh/snapshot-cleanup.json`:
+
+```json
+{ "enabled": false, "maxAgeDays": 30 }
+```
+
+- `enabled` — whether the automatic sweeps run (default `false`).
+- `maxAgeDays` — how many idle days before a long-inactive session's snapshot dir is
+  removed (default `30`; `0`/negative are rejected, so a broken config can never
+  delete everything).
+
+Override the path with the `DSH_SNAPSHOT_CLEANUP_CONFIG` environment variable.
+The file is written only by the `/snapshot-auto-cleanup` command. A missing file
+reads as the safe default (off); a missing or corrupt file makes a sweep
+**fail-closed** (delete nothing) and log a warning, and is surfaced when you run
+the command again.
+
+## When it runs
+
+The 24h window is anchored on a **persisted** last-sweep time
+(`~/.dsh/snapshot-cleanup-last-sweep.json`), so a host restart does not reset
+it: the auto-sweep checks **once per process run**, on the first session
+activity of a window (a user message or a completed tool call), and cleans only
+when enabled **and** >=24h since the last sweep. It runs in the background and
+never blocks the activity that triggered it. Because the check happens once per
+run, a change that takes effect immediately is best applied with
+`/snapshot-auto-cleanup run`; editing the config file by hand (or enabling after
+the run's first activity) takes effect on the next run.
+
+## Safety and boundaries
+
+- Removes only whole **long-inactive** session dirs; the active session and the
+  conversation log are never touched.
+- "Inactive" is judged by mtime: a session still being written to keeps scrolling
+  its newest member stamp forward, so it is never old enough to be pruned.
+- Dedup `ref` links are session-relative, so removing a whole dir cannot dangle a
+  link elsewhere.
+- Trade-off: enabling auto-cleanup means a session resumed after a long idle gap
+  will rewind only from its remaining (newest 100) anchors; its old snapshots are
+  gone. The conversation log is never affected.
+- Deleting the whole store dir manually stays safe (it is recreated on the next
+  capture); auto-cleanup just scopes that removal to long-inactive sessions.

package/docs/snapshot-auto-cleanup.zh.md

@@ -0,0 +1,42 @@
+# 快照自动清理
+
+回退插件为每次被跟踪的文件修改写入一份磁盘 `before` 备份，并按其锚点消息分组。快照在**同一会话**内去重、且保留最近 100 组锚点，但跨**已不再活跃的会话**时存储仍会无界增长。`snapshot-auto-cleanup` 是**可选**的全局策略（默认关闭）：把**长期不活跃**（失活超过可配置阈值）的会话快照**整目录**移除。
+
+它只会移除**长期不活跃**会话的整个快照目录，绝不触碰活动会话的快照、绝不触碰对话日志，也保留仍在阈值内的快照数据。
+
+## 命令
+
+```
+/snapshot-auto-cleanup                 查看状态（是否开启、max-age、配置路径）
+/snapshot-auto-cleanup on|off          开启/关闭自动清理
+/snapshot-auto-cleanup max-age <天数>  设置失活阈值（正整数）
+/snapshot-auto-cleanup run             预演：列出将移除哪些会话
+/snapshot-auto-cleanup run --apply     真正移除这些会话
+```
+
+`run` 是手动逃生舱，无论自动清理是否为 `on` 都能用；默认只预演，加 `--apply` 才执行。
+
+## 配置文件
+
+策略持久化到 `~/.dsh/snapshot-cleanup.json`：
+
+```json
+{ "enabled": false, "maxAgeDays": 30 }
+```
+
+- `enabled` — 是否运行自动清理（默认 `false`）。
+- `maxAgeDays` — 失活多少天后移除某**长期不活跃**会话的快照目录（默认 `30`；`0`/负数会被拒绝，因此损坏的配置不可能导致"删除一切"）。
+
+可用环境变量 `DSH_SNAPSHOT_CLEANUP_CONFIG` 覆盖路径。该文件只由 `/snapshot-auto-cleanup` 命令写入。文件缺失按安全默认（关闭）处理；缺失或损坏会令一次清扫**fail-closed**（不删任何东西）并写入警告，再次运行命令时会有所提示。
+
+## 运行时机
+
+24 小时窗口锚定在**持久化**的上次清扫时间（`~/.dsh/snapshot-cleanup-last-sweep.json`）上，因此宿主重启不会重置：自动清扫在**每次运行只检查一次**，于某个窗口的首次会话活动（一条用户消息或一次工具调用完成）时执行，且仅在**已启用**且距上次清扫 **>=24 小时**时才清理。它后台运行，从不阻塞触发它的活动。由于每次运行只检查一次，想让改动立即生效最好用 `/snapshot-auto-cleanup run`；手动编辑配置文件（或在本次运行的首次活动之后才开启）会到下次运行才生效。
+
+## 安全与边界
+
+- 只移除**长期不活跃**会话的整目录；活动会话与对话日志永不触碰。
+- "不活跃"以 mtime 判定：仍在写入的会话会不断把"最新成员"时间戳往后推，因此永远到不了可被清理的失活阈值。
+- 去重 `ref` 链接是会话内相对的，所以移除整目录不会让别处产生悬空链接。
+- 权衡：开启自动清理后，某个长时间闲置才被重新打开的会话，只能从剩余（最近 100 组）锚点回退，旧快照已不存在；对话日志永不受影响。
+- 手动删除整个存储目录依然安全（下次捕获时自动重建）；自动清理只是把这种删除限定到长期不活跃的会话。