@summerscar/dsh-mnemon-sync 0.1.0 → 0.1.2

package/README.md

@@ -1,86 +1,43 @@
 # dsh-mnemon-sync
 
-为 [dsh-mnemon](https://github.com/omdsh-dev/dsh-mnemon) 提供备份与恢复：把 Mnemon 的记忆组件打包上传到 S3 兼容存储或 WebDAV，需要时再挑一个包恢复回来。
+为 [dsh-mnemon](https://github.com/omdsh-dev/dsh-mnemon) 提供备份与恢复：把记忆组件打包上传到 S3 兼容存储或 WebDAV，需要时挑一个包恢复回来。安装后在记忆系统里多一个「同步备份」标签页。
 
-在记忆系统里以「同步备份」标签页出现，和「概览」「检索」「内容」并排。
-
-## 能备份什么
-
-按 dsh-mnemon 自己的组件划分，任意组合，多选：
-
-| 组件 | 内容 | 说明 |
-|---|---|---|
-| 记忆空间 | `<MNEMON_DATA_DIR>/data/` | 每个空间的 `mnemon.db` 与空间清单，数据库经 SQLite 在线备份 |
-| 项目档案 | `<MNEMON_DATA_DIR>/documents/` | `index.json` 与全部 Markdown 文档 |
-| 运行时记忆 | `<MNEMON_DATA_DIR>/runtime/` | `memories.json` 与两份投影文件 |
-
-`MNEMON_DATA_DIR` 未设置时取 `~/.mnemon`。
-
-## 为什么不用 litestream
-
-litestream 是很好的工具，但和「目录级、多空间、可配置目标」这个需求是正交的：
+## 安装
 
-- 一个 litestream 实例只盯一个数据库文件，v0.5 起每个数据库只允许一个副本。要备份整个 data 目录就得为每个记忆空间养一个常驻进程，空间增删还得动态改配置。
-- 它接管 WAL checkpoint 并长期持有读锁。实测会让 `mnemon.db-wal` 停在非零字节，而 dsh-mnemon 自己的备份导出有这条检查：
+```sh
+dsh plugin --profile web add @summerscar/dsh-mnemon-sync
+```
 
-  ```js
-  if (existsSync(wal) && statSync(wal).size > 0)
-    throw new Error(`Memory Space ${id} is busy (mnemon.db-wal is not checkpointed)`)
-  ```
+装完重启 DSH 生效。没有 `dsh-mnemon` 时插件仍可运行，只是不显示标签页。
 
-  也就是说上了 litestream，dsh-mnemon 自带的备份会直接报错。
+## 能备份什么
 
-这里改用 `node:sqlite` 的 `backup()`：它走 SQLite 自己的在线备份 API，写入方持有 WAL 也不会把副本撕开，并发写只会让备份重跑当前批次，不产生常驻进程。
+三个组件任意组合，默认全选：
 
-## 一致性
+| 组件 | 内容 |
+|---|---|
+| 记忆空间 | `<MNEMON_DATA_DIR>/data/`，每个空间的 `mnemon.db` 与空间清单 |
+| 项目档案 | `<MNEMON_DATA_DIR>/documents/`，`index.json` 与全部 Markdown |
+| 运行时记忆 | `<MNEMON_DATA_DIR>/runtime/`，`memories.json` 与两份投影 |
 
-- **数据库**：`backup()` 生成事务一致的副本，产物是已 checkpoint 的单文件，不含 `-wal` / `-shm`。
-- **非数据库文件**：JSON 与 Markdown 由存储层原子写入，逐字节复制。
-- **校验**：每个文件在打包前记录 SHA-256，manifest 与内容一起入包；上传前先自校验，恢复前再校验一次。
-- **恢复顺序**：先下载 → 校验全部校验和 → 报告缺失组件 → 只写回确认的组件。不带 `apply` 时是纯预览，不碰磁盘。
-- **覆盖数据库前**会先删除同名的 `-wal` / `-shm`：残留的 WAL 会让 SQLite 重放恢复文件里并不存在的事务。
+`MNEMON_DATA_DIR` 未设置时取 `~/.mnemon`。
 
-## 目标
+## 备份目标
 
-- **S3 兼容**：AWS Signature V4 手写实现，已用 AWS 官方文档的测试向量逐字节校验。适用于 Cloudflare R2、MinIO、Backblaze B2、阿里云 OSS 等。
-- **WebDAV**：`PUT` 上传、`PROPFIND depth:1` 列目录、`DELETE` 清理，Basic 认证。
+- **S3 兼容** — 手写 AWS Signature V4，适用于 Cloudflare R2、MinIO、Backblaze B2 等
+- **WebDAV** — Basic 认证，自动创建远端目录
 
-凭据保存在 `<MNEMON_DATA_DIR>/state/mnemon-sync.json`，权限 `0600`，不进 DSH 配置，也不会被备份包带走（`state/` 不属于任何备份组件）。页面回显密钥时只给掩码，回传掩码表示"不修改"。
+凭据存在 `<MNEMON_DATA_DIR>/state/mnemon-sync.json`，权限 `0600`，不写入 DSH 配置，也不进备份包。页面只回显掩码，回传掩码表示不修改。
 
 ## 自动备份
 
-间隔与 dsh-mnemon 自己的 Git 备份保持一致，两项功能读起来一样：
-
 关闭 · 每小时 · 每 3 / 6 / 12 小时 · 每天 · 每 3 天 · 每 7 天
 
-调度是一个 Host 内唯一的 `setTimeout` 自循环，从 `finally` 里重新排期。每次触发前重新读配置，改间隔不用重启；运行中再次触发会被丢弃而不是排队；失败只记录不抛出。
+## 恢复
 
-## 安装
+从备份列表查看明细，选择要恢复的组件后执行；缺少的组件会明确提示。恢复默认只做预览，确认后才写盘。
 
-```sh
-git clone https://github.com/summerscar/dsh-mnemon-sync.git
-```
-
-在 DSH 里用插件管理器安装这个目录，或直接加入 profile 的依赖：
-
-```sh
-dsh plugin --profile web add /path/to/dsh-mnemon-sync
-```
-
-需要在 profile 里启用，并确保 `mnemon.sync` 这一层出现在 `memoryTopology.layers` 中。插件会注册一个最小 Source 来承载自己的页面 —— dsh-mnemon 只会为真实存在的 Source 渲染标签页，且标签高亮按 `sourceTypeId` 分组，借用别人的类型会导致两个标签同时点亮。
-
-## 目录结构
-
-```
-index.js      Host 入口：HTTP 接口、调度装配、Source 注册
-source.js     承载页面身份的最小 Source（不存记忆）
-snapshot.js   组件识别、数据库在线备份、manifest 与校验
-scheduler.js  定时器与运行历史
-store.js      设置存取（0600）与规范化
-targets.js    S3 SigV4 / WebDAV 的上传、下载、列目录、删除
-zip.js        零依赖 ZIP 读写（node:zlib）
-client.js     浏览器端页面与标签注册
-```
+数据库用 `node:sqlite` 的 `backup()` 在线备份，副本一致；写回前会删掉同名 `-wal` / `-shm`，避免 SQLite 重放不存在的事务。每个文件都有 SHA-256 校验。
 
 ## 许可
 

package/client.js

@@ -40,8 +40,8 @@ window.__ModuleLoader__.load({
 
     const zh = {
       tabLabel: '同步备份',
-      title: '记忆空间同步备份',
-      subtitle: '把 Mnemon 的记忆组件打包上传到 S3 或 WebDAV',
+      title: '同步备份',
+      subtitle: '把选定的记忆组件打包备份到 S3 兼容存储或 WebDAV，并可随时查看备份列表与恢复。',
       config: '备份配置',
       configNote: '以下三项一起保存。',
       scope: '备份范围',
@@ -56,6 +56,7 @@ window.__ModuleLoader__.load({
       componentSpaces: '{count} 个空间',
       backups: '备份列表',
       listBackups: '从目标列出备份',
+      refresh: '刷新',
       backupsHint: '列出远端已存在的备份包，可查看明细并恢复。',
       noBackups: '目标上还没有备份包',
       backupName: '文件名',
@@ -118,7 +119,6 @@ window.__ModuleLoader__.load({
       backingUp: '备份中…',
       backupDone: '备份完成',
       backupFailed: '备份失败',
-      never: '从未',
       history: '运行记录',
       noHistory: '还没有运行记录',
       ok: '成功',
@@ -129,6 +129,9 @@ window.__ModuleLoader__.load({
       duration: '耗时',
       size: '体积',
       componentsCount: '组件',
+      clearHistory: '清空记录',
+      historyCleared: '运行记录已清空',
+      clearFailed: '清空失败',
       error: '错误',
       loading: '读取中…',
       loadFailed: '读取失败',
@@ -141,8 +144,8 @@ window.__ModuleLoader__.load({
 
     const en = {
       tabLabel: 'Sync backup',
-      title: 'Memory space sync backup',
-      subtitle: 'Pack Mnemon\u2019s memory components to S3 or WebDAV',
+      title: 'Sync backup',
+      subtitle: 'Back up selected memory components to S3-compatible storage or WebDAV, with an archive list and restore.',
       config: 'Backup settings',
       configNote: 'All three sections below save together.',
       scope: 'Backup scope',
@@ -157,6 +160,7 @@ window.__ModuleLoader__.load({
       componentSpaces: '{count} spaces',
       backups: 'Backups',
       listBackups: 'List from target',
+      refresh: 'Refresh',
       backupsHint: 'List the archives already on the target, inspect one, and restore it.',
       noBackups: 'No archive on the target yet',
       backupName: 'File',
@@ -229,6 +233,9 @@ window.__ModuleLoader__.load({
       duration: 'Duration',
       size: 'Size',
       componentsCount: 'Components',
+      clearHistory: 'Clear log',
+      historyCleared: 'Run history cleared',
+      clearFailed: 'Could not clear',
       error: 'Error',
       loading: 'Loading\u2026',
       loadFailed: 'Could not load',
@@ -657,6 +664,24 @@ window.__ModuleLoader__.load({
         }
       }
 
+      /**
+       * Drop the run log. Archives on the target are not touched — this is a
+       * display reset, and the page says so before the button is pressed.
+       */
+      const clearHistory = async () => {
+        setBusy(true)
+        setNotice(null)
+        try {
+          await api('/clear-history', { method: 'POST', body: '{}' })
+          await load()
+          setNotice({ ok: true, text: t('historyCleared') })
+        } catch (cause) {
+          setNotice({ ok: false, text: `${t('clearFailed')}: ${cause.message}` })
+        } finally {
+          setBusy(false)
+        }
+      }
+
       const loadArchives = async () => {
         setArchivesBusy(true)
         setArchivesError(null)
@@ -1082,7 +1107,15 @@ window.__ModuleLoader__.load({
 
         // history
         h('section', { style: styles.card },
-          h('h3', { style: styles.cardTitle }, t('history')),
+          h('div', { style: styles.row },
+            h('h3', { style: { ...styles.cardTitle, marginRight: 'auto' } }, t('history')),
+            // The list keeps the newest 20 on its own; this clears what is left.
+            history.length === 0 ? null : h('button', {
+              style: styles.button,
+              disabled: busy,
+              onClick: () => void clearHistory(),
+            }, t('clearHistory')),
+          ),
           history.length === 0
             ? h('p', { style: styles.note }, t('noHistory'))
             : h('table', { style: styles.table },

package/index.js

@@ -199,19 +199,8 @@ export function apply(ctx, config = {}) {
 
     if (req.method === 'PUT' && route === '/settings') {
       const body = await readJsonBody(req)
-      const previous = settings()
       const incoming = body?.settings ?? body
-      // A masked secret coming back from the UI means "unchanged".
-      if (incoming !== null && typeof incoming === 'object' && incoming.target !== null && typeof incoming.target === 'object') {
-        const target = incoming.target
-        if (target.kind === 'webdav' && isMasked(target.password)) {
-          target.password = previous.target.kind === 'webdav' ? previous.target.password : ''
-        }
-        if (target.kind === 's3' && isMasked(target.secretAccessKey)) {
-          target.secretAccessKey = previous.target.kind === 's3' ? previous.target.secretAccessKey : ''
-        }
-      }
-      const saved = writeSettings(home, normalizeSettings(incoming))
+      const saved = writeSettings(home, normalizeSettings(restoreMaskedSecrets(incoming, settings())))
       scheduler.refresh()
       sendJson(res, 200, { settings: maskSettings(saved) })
       return
@@ -225,7 +214,10 @@ export function apply(ctx, config = {}) {
       const body = await readJsonBody(req)
       try {
         if (body?.settings !== undefined) {
-          const saved = writeSettings(home, normalizeSettings(body.settings))
+          // The same masked-secret rule as saving settings: the page always
+          // sends the mask it was shown, and writing that mask as the real
+          // password would silently break the next upload with a 401.
+          const saved = writeSettings(home, normalizeSettings(restoreMaskedSecrets(body.settings, settings())))
           scheduler.refresh()
           const result = await scheduler.runNow('manual')
           sendJson(res, 200, { result, settings: maskSettings(saved) })
@@ -239,6 +231,12 @@ export function apply(ctx, config = {}) {
       return
     }
 
+    if (req.method === 'POST' && route === '/clear-history') {
+      // Only the local run log is cleared; archives on the target are untouched.
+      sendJson(res, 200, { history: history.clear() })
+      return
+    }
+
     if (req.method === 'POST' && route === '/refresh-schedule') {
       scheduler.refresh()
       sendJson(res, 200, { scheduler: scheduler.snapshot(settings()) })
@@ -557,6 +555,33 @@ function isMasked(value) {
   return typeof value === 'string' && value !== '' && /^•+$/u.test(value)
 }
 
+/**
+ * Put the real secrets back into a settings payload that arrived masked.
+ *
+ * The page never receives a secret — `maskSettings` replaces it with bullets —
+ * and echoes those bullets back on every save. Treating them as a value would
+ * overwrite the real credential with eight bullet characters, which is exactly
+ * what made a correctly configured WebDAV target answer 401: the stored
+ * password really was `••••••••`.
+ *
+ * Any write path that accepts settings from the browser must run this first.
+ */
+function restoreMaskedSecrets(incoming, previous) {
+  if (incoming === null || typeof incoming !== 'object') return incoming
+  const target = incoming.target
+  if (target === null || typeof target !== 'object') return incoming
+  if (target.kind === 'webdav' && isMasked(target.password)) {
+    target.password = previous.target.kind === 'webdav' ? previous.target.password : ''
+  }
+  if (target.kind === 's3' && isMasked(target.secretAccessKey)) {
+    target.secretAccessKey = previous.target.kind === 's3' ? previous.target.secretAccessKey : ''
+  }
+  if (target.kind === 's3' && isMasked(target.sessionToken)) {
+    target.sessionToken = previous.target.kind === 's3' ? previous.target.sessionToken : ''
+  }
+  return incoming
+}
+
 /**
  * Resolve the dsh-mnemon extension SDK.
  *

package/locale/en.json

@@ -1,6 +1,6 @@
 {
   "meta": {
-    "title": "Memory space sync backup",
-    "description": "Archive the whole Mnemon data directory — every memory space database — to S3-compatible storage or WebDAV, with minute/hour/day/clock scheduling and retention."
+    "title": "Sync backup",
+    "description": "Back up and restore dsh-mnemon memory components (memory spaces, project documents, runtime memory — pick any subset) to S3-compatible storage or WebDAV, with scheduled backups, an archive list and selective restore."
   }
 }

package/locale/zh.json

@@ -1,6 +1,6 @@
 {
   "meta": {
-    "title": "记忆空间同步备份",
-    "description": "把整个 Mnemon data 目录（含全部记忆空间数据库）打包备份到 S3 兼容存储或 WebDAV，支持按分钟/小时/天/固定时刻调度与保留份数。"
+    "title": "同步备份",
+    "description": "备份与恢复 dsh-mnemon 的记忆组件（记忆空间、项目档案、运行时记忆，可任选）到 S3 兼容存储或 WebDAV，支持定时备份、备份列表与选择性恢复。"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@summerscar/dsh-mnemon-sync",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Back up and restore dsh-mnemon memory components (memory spaces, project documents, runtime memory) to S3-compatible storage or WebDAV.",
   "type": "module",
   "main": "index.js",

package/scheduler.js

@@ -72,6 +72,22 @@ export class SyncHistory {
   latest() {
     return this.read()[0]
   }
+
+  /**
+   * Drop the whole run history.
+   *
+   * History is a display convenience, not a record of truth: the archives
+   * themselves live on the target, and retention keys off the same list, so
+   * clearing it simply stops the page from showing past runs. Retention then
+   * has nothing to delete, which is the honest outcome — after clearing, this
+   * plugin no longer knows which keys it uploaded.
+   */
+  clear() {
+    const path = this.path()
+    mkdirSync(join(this.root, STATE_DIRECTORY), { recursive: true, mode: 0o700 })
+    writeFileSync(path, `${JSON.stringify({ version: 1, runs: [] }, null, 2)}\n`, { mode: 0o600 })
+    return []
+  }
 }
 
 /**