@sparkelf/dsh-plugin-backup 0.1.0-rc.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+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.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/plus/backup/README.md
+README.md: 627c96595000ade5cb802da1de23cd5f6b95bcae
+README.zh.md: ac763584453417834a2bc920755651a5e25aeb0e

package/README.md

@@ -0,0 +1,67 @@
+---
+description: "Streamed, authenticated export and validated restore of file-backed DSH user data with browser progress."
+kind: "package-reference"
+---
+
+# @sparkelf/dsh-plugin-backup
+
+English | [中文](README.zh.md)
+
+## Summary
+
+This complete Host and Client plugin exports a file-backed DSH home as a ZIP archive, validates and restores an uploaded archive, reopens Workspace storage, and contributes the localized Backup Settings section. Export, upload, and import stream through Host temporary files with bounded NDJSON progress; import validates the manifest, paths, and expanded byte total before Workspace mutation.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Mount the Host entry after `connection`, `webServer`, `settings`, and `workspaceRegistry`, and mount the Client entry after locale and Settings. The file-backed Settings provider supplies `settings.documentPath`; `maxUploadBytes` defaults to 2147483648 bytes.
+
+The authenticated routes are POST `/api/backup.export.prepare`, GET/HEAD `/api/backup.export`, POST `/api/backup.upload`, and POST `/api/backup.import`. Every route applies Connection Host, Origin, and browser-authentication policy before request data. Tokens expire after ten minutes and are single-use, except HEAD metadata inspection.
+
+Once restore writes begin, closing the page does not interrupt replacement. Workspace storage closes around file replacement and reopens before completion; the Client releases the completed progress stream reader before the UI offers one explicit reload. Client failures remain visible in the Backup section without browser console errors.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+### Backup operations
+
+#### What the model sees
+
+Nothing. `@sparkelf/dsh-plugin-backup` keeps Backup archives, progress, failures, and restored files in Host storage and the Settings UI; this package registers no model-facing tool, prompt section, or Session event.
+
+#### Token effect
+
+Zero. Backup operations add no model-request tokens.
+
+#### KV Cache effect
+
+Independent. Export, import, progress, and reload do not change a model request prefix.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **Overwrite without rollback**: restore replaces same-name files, retains files absent from the archive, and creates no rollback copy if a disk write fails after mutation begins.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers, click to expand</summary>
+
+This Dev Note is working context for maintainers; shipped behavior, limits, and rationale live in the sections above, the package code, and the linked Agent Note.
+
+- The [Backup Agent Note](../../../.agents/notes/proposed/architecture/2026-08-30-plus-backup-plugin.md) owns archive, route, restore, and progress decisions; `src/index.ts` and `src/client/BackupSection.tsx` own current behavior.
+
+</details>

package/README.zh.md

@@ -0,0 +1,67 @@
+---
+description: "为file-backed DSH user data提供streamed authenticated export、validated restore及browser progress。"
+kind: "package-reference"
+---
+
+# @sparkelf/dsh-plugin-backup
+
+[English](README.md) | 中文
+
+## 概述
+
+该完整Host及Client plugin把file-backed DSH home导出为ZIP archive，验证并恢复uploaded archive，重新打开Workspace storage，并贡献localized Backup Settings section。Export、upload和import通过Host temporary files stream并提供bounded NDJSON progress；import会在Workspace mutation前验证manifest、paths及expanded byte total。
+
+## 目录
+
+- [使用此软件包](#use-this-package)
+- [模型体验](#model-experience)
+- [已知限制和延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用此软件包
+
+Host entry需mount在`connection`、`webServer`、`settings`及`workspaceRegistry`之后，Client entry需mount在locale及Settings之后。file-backed Settings provider提供`settings.documentPath`；`maxUploadBytes`默认为2147483648 bytes。
+
+authenticated routes为POST `/api/backup.export.prepare`、GET/HEAD `/api/backup.export`、POST `/api/backup.upload`及POST `/api/backup.import`。每条route会在读取request data前应用Connection Host、Origin及browser-authentication policy。Token在十分钟后过期并且single-use，HEAD metadata inspection除外。
+
+一旦restore开始写入，关闭page不会中断replacement。Workspace storage会在file replacement期间关闭并在completion前重新打开；Client会先释放completed progress stream reader，再由UI提供一次explicit reload。Client failure保留在Backup section可见状态，不产生browser console error。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### Backup operations
+
+#### 模型看到什么
+
+没有内容。`@sparkelf/dsh-plugin-backup`把Backup archives、progress、failures及restored files留在Host storage和Settings UI；该package不注册model-facing tool、prompt section或Session event。
+
+#### Token 影响
+
+为零。Backup operations不增加model-request tokens。
+
+#### KV Cache 影响
+
+独立。Export、import、progress及reload不改变model request prefix。
+
+## 已知限制和延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **Overwrite without rollback**：restore会替换same-name files，保留archive中不存在的files，并且在mutation开始后disk write失败时不创建rollback copy。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作上下文，点击展开</summary>
+
+该开发备注是maintainer working context；shipped behavior、limits及rationale以以上sections、package code及linked Agent Note为准。
+
+- [Backup Agent Note](../../../.agents/notes/proposed/architecture/2026-08-30-plus-backup-plugin.zh.md)持有archive、route、restore及progress decisions；`src/index.ts`和`src/client/BackupSection.tsx`持有current behavior。
+
+</details>