dsh-session-autarchive 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-session-autarchive contributors
+
+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.en.md

@@ -0,0 +1,104 @@
+# dsh-session-autarchive
+
+<img src="assets/icon-180.png" width="96" align="right" alt="dsh-session-autarchive">
+
+[中文](README.md) | **English**
+
+Archives sessions that have gone unused for longer than a configurable number of days (5 by default). Archived sessions, pinned sessions (exempt by default), and sessions marked "do not auto-archive" are skipped. A session context-menu item marks a single session, and a field in General settings changes the threshold.
+
+## Where it shows up
+
+| Where | What it looks like | What it does |
+|---|---|---|
+| Session context menu | One row, "Do not auto-archive", next to Pin / Rename / Fork / Archive | Click once to mark, again to unmark |
+| Session row start | A small shield on marked sessions | Shows at a glance that the session is protected |
+| Hover card | One line, "Not auto-archived" | Same, with text |
+| General settings | A row at the bottom, "Auto-archive after (days)" | Saved on blur or Enter, writes the same host field |
+
+## How it decides and runs
+
+- **Decision**: scan `$DSH_HOME/sessions/<workspace>/session-*` directories, take the newest file time inside each as "last activity". Sessions older than the threshold (5 days by default), not yet archived, not on the protected list, and not pinned (pinning is exempt by default) become pending sessions.
+- **Execution**: the host runs a round every 10 minutes (the first one 60 seconds after start, so it keeps running even with no window open); the browser half polls the pending list every 5 minutes and archives through the official channel when it is available, so the sidebar updates immediately.
+- Archiving goes through the official `archiveSession` call. It does not delete data: archived sessions stay in the archive list and can be restored.
+
+## Install
+
+```sh
+dsh plugin --profile desktop add github:taoziliyouchong/dsh-session-autarchive
+```
+
+Restart DSH afterwards. Replace `desktop` with your own profile name if you use another one.
+
+Compatible with DSH 0.2.1-rc.5 (tested); 0.3 and later are not guaranteed.
+
+Once published to npm, this also works:
+
+```sh
+dsh plugin --profile desktop add dsh-session-autarchive
+```
+
+**It is enabled by default with a 5-day threshold.** Installing it starts archiving by that rule. To turn it off first:
+
+```sh
+# tool dsh-session-autarchive, action=config, enabled=false
+```
+
+## Tool
+
+The tool is named `dsh-session-autarchive` and takes five actions:
+
+| action | What it does |
+|---|---|
+| `status` (default) | Configuration summary, pending sessions, protected list, last run |
+| `run` | Archive the pending sessions now; `dryRun: true` lists them without touching anything |
+| `protect` | Mark one session "do not auto-archive" (needs `sessionId`) |
+| `unprotect` | Remove the mark |
+| `config` | Change `days`, `enabled`, `exemptPinned` |
+
+## Data files
+
+All under `$DSH_HOME/session-autarchive/`:
+
+| File | Written by | Notes |
+|---|---|---|
+| `protected.json` | protect / unprotect only | The single source of the protected list. The archive timer never writes it, so a run cannot wash the marks away. |
+| `state.json` | archive rounds, config | Switch, threshold, pin exemption, last run result; holds no list. |
+| `audit.log` | list changes, every round | One line each, so a lost mark can be traced by time. |
+
+Writes are temp-file-then-rename, and reads retry — a half-written file is never mistaken for "no list" and overwritten with defaults.
+
+## How it works
+
+- The host half registers four local routes: `GET /dsh-session-autarchive/api/state`, `POST .../protect`, `POST .../config`, `POST .../run`. Loopback addresses only (`127.*`, `::1`, `::ffff:127.*`); anything else gets 403, a wrong method gets 405.
+- The browser half mounts four slots (menu row, row start, hover card, settings row). Services are probed with `ctx.get`; when one is missing that entry is skipped and the others still mount.
+- No network access, nothing uploaded. Decisions use local file times only.
+
+## Known limits
+
+- Without a `workspaceRegistry` service on the host side, the host can only list pending sessions and cannot archive by itself; the browser half then executes through the official channel.
+- Only sessions stored under `$DSH_HOME/sessions` are considered.
+- Do not install another auto-archive plugin alongside this one: the same UI slots can only be claimed once, and duplicates show the menu row and the settings row twice.
+- Enabled by default: it starts archiving at the 5-day threshold right after install. To watch first, set `enabled` to `false` or raise `days`.
+
+## Development
+
+The source has two halves:
+
+- `index.js` — host side (decision, archiving, four routes, the tool)
+- `src/entry.jsx` — browser side (menu row, row shield, hover line, settings row, the 5-minute fast path)
+
+Editing `src/entry.jsx` requires rebuilding. `lib/client.js` is a build artifact committed to the repository; without it the UI does not load:
+
+```sh
+npm install
+npm run build:client    # regenerate lib/client.js
+npm run check:client    # verify the committed artifact matches the source
+npm run smoke           # structure / bundle manifest / registration / authorization / state / artifact
+npm run check           # syntax
+```
+
+The smoke run uses a temporary `$DSH_HOME`; it never reads or changes your session data. Build rules: keep `react` and `react/jsx-runtime` external (the DSH client module table provides them); the `id` inside the `window.__ModuleLoader__.load({ id, factory })` envelope must equal the package name.
+
+## License
+
+MIT

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+# dsh-session-autarchive
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<img src="assets/icon-180.png" width="96" align="right" alt="dsh-session-autarchive">
+
+**中文** | [English](README.en.md)
+
+把长期没动过的会话自动归档。按会话档的最后写入时间算天数，默认 5 天；已归档、置顶（可关）、标记「不自动归档」的都跳过。侧栏会话右键菜单给单个会话加标记，通用设置里改天数。
+
+## 界面上的三处
+
+| 位置 | 样子 | 作用 |
+|---|---|---|
+| 会话右键菜单 | 与「置顶会话／重命名／分叉会话／归档会话」并列的一行「不自动归档」 | 点一次标记，再点一次取消 |
+| 会话行首 | 被标记的会话多一个小盾牌 | 一眼看出这条不会被自动归档 |
+| 悬停卡片 | 一行「不会被自动归档」 | 同上，带文字说明 |
+| 通用设置 | 最底一行「自动归档天数」 | 失焦或回车即保存，写的是宿主同一个字段 |
+
+## 判定与执行
+
+- **判定**：扫 `$DSH_HOME/sessions/<工作区>/session-*` 目录，取目录内最新文件时间当「最后活动」；超过阈值（默认 5 天）、未归档、不在保护名单、非置顶（置顶豁免默认开）的就是待归档的会话。
+- **执行**：宿主每 10 分钟跑一轮（启动 60 秒后第一次，窗口没开也照常跑）；浏览器半边每 5 分钟拉一次待归档清单，拿到官方归档通道就当场归档，侧栏立即刷新。
+- 归档走官方 `archiveSession`，不是删数据。归档后的会话在侧栏归档列表里，可以恢复。
+
+## 安装
+
+```sh
+dsh plugin --profile desktop add github:taoziliyouchong/dsh-session-autarchive
+```
+
+装完重启 DSH。用别的 profile 就把 `desktop` 换成你的 profile 名。
+
+兼容：DSH 0.2.1-rc.5 实测通过；0.3 起不保证。
+
+发布到 npm 之后也可以：
+
+```sh
+dsh plugin --profile desktop add dsh-session-autarchive
+```
+
+**注意：默认开启，阈值 5 天。** 装好就会开始按这个口径归档。不想让它动，先关掉：
+
+```sh
+# 工具 dsh-session-autarchive，action=config，enabled=false
+```
+
+## 工具
+
+工具名 `dsh-session-autarchive`，五个动作：
+
+| action | 做什么 |
+|---|---|
+| `status`（默认） | 配置摘要、当前待归档会话、保护名单、最近一次执行 |
+| `run` | 立刻归档当前待归档会话；`dryRun: true` 只列清单不动手 |
+| `protect` | 标记单个会话「不自动归档」（要 `sessionId`） |
+| `unprotect` | 取消标记 |
+| `config` | 改 `days`（天数）、`enabled`（开关）、`exemptPinned`（置顶是否豁免） |
+
+## 数据文件
+
+都在 `$DSH_HOME/session-autarchive/`：
+
+| 文件 | 写它的地方 | 说明 |
+|---|---|---|
+| `protected.json` | 只有 protect／unprotect | 保护名单的唯一来源。自动归档那条定时链不碰它，怎么跑都洗不掉标记。 |
+| `state.json` | 定时归档、config | 开关、阈值、置顶豁免、最近一次执行结果；不存名单。 |
+| `audit.log` | 名单改动、每轮归档 | 一行一条，标记哪天没了可以对着时间查。 |
+
+写入一律「临时文件 + 改名」，读盘失败会重试——不会把半截文件当成「没有名单」再把默认值写回去。
+
+## 机制
+
+- 宿主半边注册四条本机路由：`GET /dsh-session-autarchive/api/state`、`POST .../protect`、`POST .../config`、`POST .../run`。只接受回环地址（`127.*`、`::1`、`::ffff:127.*`），远程访问一律 403；方法不对 405。
+- 浏览器半边用 `ctx.slots` 挂四个座位（菜单行、行首、悬停、设置行），服务探测一律 `ctx.get`，拿不到就跳过，不影响其他入口。
+- 不联网、不上传任何内容；判定只用本地文件时间。
+
+## 已知限制
+
+- 宿主侧没有 `workspaceRegistry` 服务时，只能列出待归档会话、不能自己归档；此时由浏览器半边走官方通道执行。
+- 只扫 `$DSH_HOME/sessions` 下的会话档；不在这个目录里的会话不参与判定。
+- 不要与另一个自动归档插件同时安装：同一组界面座位只能挂一份，重复安装会出现两行菜单和两行设置。
+- 默认开启：装好就会按 5 天阈值归档。想先观察，把 `enabled` 改成 `false`，或把 `days` 调大。
+
+## 开发
+
+源码分两半：
+
+- `index.js` —— 宿主半边（判定、归档、四条路由、工具）
+- `src/entry.jsx` —— 浏览器半边（菜单行、行首盾牌、悬停说明、设置行、5 分钟快通道）
+
+改过 `src/entry.jsx` 必须重新打包。`lib/client.js` 是提交进仓库的构建产物，缺了它界面不会加载：
+
+```sh
+npm install
+npm run build:client    # 重新生成 lib/client.js
+npm run check:client    # 比对新产物与已提交产物是否一致
+npm run smoke           # 结构 / 组合声明 / 注册 / 鉴权 / 状态读写 / 产物
+npm run check           # 语法
+```
+
+冒烟全程用临时 `$DSH_HOME`，不读也不改你的会话数据。打包要求：`react` 与 `react/jsx-runtime` 保持 external（由 DSH 客户端模块表提供）；产物外壳 `window.__ModuleLoader__.load({ id, factory })` 里的 `id` 必须等于包名。
+
+## 许可
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# dsh-session-autarchive：宿主半边（定时判定与归档、四条本机路由、一个工具）
+# 与浏览器半边（会话菜单标记、行首盾牌、设置里的天数）在同一行。
+- insert:
+    - id: dsh-session-autarchive
+      name: dsh-session-autarchive