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

package/lib/invariant.js

@@ -0,0 +1,18 @@
+//#region lib/types/invariant.js
+/** Package invariant companion for `@sparkelf/dsh-plugin-backup`. */
+const PACKAGE_NAME = "@sparkelf/dsh-plugin-backup";
+const name = "plus-backup-invariant";
+const inject = ["invariants"];
+/**
+* No runtime invariant: WebServer owns route registration, Workspace owns its
+* durable/cache relation, and the browser settings slot has no Host projection.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Host context carrying the invariant registry.
+* @returns the registration disposer.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/archive.d.ts

@@ -0,0 +1,63 @@
+/**
+ * User data backup core for the web settings Backup section. Export scans one
+ * stable file plan, reads and compresses bounded chunks, and publishes source-
+ * byte progress. Import validates before mutation, then writes bounded chunks
+ * while publishing restored-byte progress.
+ */
+import type { BackupProgressReporter } from './protocol.ts';
+/**
+ * Pack the harness home's user configuration and data into a zip archive,
+ * publishing scan and source-byte compression progress. A failed export removes
+ * its partial archive.
+ * @param dshHome - harness user data directory (settings.yaml parent).
+ * @param targetPath - absolute file path the archive is written to.
+ * @param signal - caller or response cancellation.
+ * @param report - ordered progress writer.
+ * @returns the number of zip entries including the manifest marker.
+ */
+export declare function writeUserBackup(dshHome: string, targetPath: string, signal: AbortSignal, report: BackupProgressReporter): Promise<{
+    entries: number;
+}>;
+/** One validated archive entry staged outside the harness home. */
+type ValidatedBackupEntry = {
+    kind: 'directory';
+    relativePath: string;
+} | {
+    kind: 'file';
+    relativePath: string;
+    size: number;
+};
+/** An archive fully validated and extracted to a temporary directory before user-data mutation. */
+export interface ValidatedUserBackup {
+    /** Temporary extraction root containing every validated regular file. */
+    stagingRoot: string;
+    /** Validated portable entries in archive order. */
+    entries: ValidatedBackupEntry[];
+    /** Number of zip entries including the manifest marker. */
+    count: number;
+    /** Total regular-file bytes restored into the harness home. */
+    totalBytes: number;
+}
+/**
+ * Validate and extract one staged zip without retaining archive or entry bodies in memory.
+ * @param archivePath - disk-staged raw upload.
+ * @param stagingRoot - temporary extraction root outside the harness home.
+ * @param maxExpandedBytes - aggregate expanded-byte limit shared with upload admission.
+ * @param signal - response cancellation honored until DSH-home mutation begins.
+ * @returns the validated staged entry plan.
+ */
+export declare function validateUserBackup(archivePath: string, stagingRoot: string, maxExpandedBytes: number, signal: AbortSignal): Promise<ValidatedUserBackup>;
+/**
+ * Write a validated staged archive over the harness home while publishing restored bytes.
+ * Once file mutation begins the operation completes rather than honoring a late response
+ * cancellation, so user data is not left half-written by closing a page.
+ * @param validated - validateUserBackup result.
+ * @param dshHome - harness user data directory.
+ * @param report - ordered progress writer; a disconnected response may ignore updates.
+ * @returns the restored entry count.
+ */
+export declare function restoreUserBackup(validated: ValidatedUserBackup, dshHome: string, report: BackupProgressReporter): Promise<{
+    entries: number;
+}>;
+export {};
+//# sourceMappingURL=archive.d.ts.map

package/lib/types/client/BackupSection.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Backup settings section: exact Host routes stream archive bytes and progress;
+ * the slot store survives settings-driven component remounts.
+ */
+import type { ReactNode } from 'react';
+import type { InjectFace, PropsLocale, PropsRuntime, PropsStore } from '@deepseek-ai/dsh-client-ui-slots';
+import type { BackupSectionStore } from './store.ts';
+import type { BackupSectionProgress } from './types.ts';
+/** Registration-side business face for the two streamed backup operations. */
+export interface BackupSectionInjected {
+    /**
+     * Prepare a fresh export while reporting real source-byte progress.
+     * @param report - receives ordered progress updates.
+     * @returns the single-use browser download URL and entry count.
+     */
+    exportArchive(report: (progress: BackupSectionProgress) => void): Promise<{
+        downloadUrl: string;
+        entries: number;
+    }>;
+    /**
+     * Upload and restore one picked archive while reporting transport and Host progress.
+     * @param file - browser-selected backup archive.
+     * @param report - receives ordered progress updates.
+     * @returns the restored entry count.
+     */
+    importArchive(file: File, report: (progress: BackupSectionProgress) => void): Promise<{
+        entries: number;
+    }>;
+    /** Cancel the active operation while its current phase still permits cancellation. */
+    cancelOperation(): void;
+    /** Reload the browser so it fetches restored session and workspace baselines. */
+    reloadPage(): void;
+}
+/** Full component props. */
+export type BackupSectionProps = PropsRuntime<'settings.section'> & PropsLocale<'settingsBackup'> & PropsStore<BackupSectionStore> & InjectFace<BackupSectionInjected>;
+/**
+ * The Backup section body.
+ * @param props - runtime owner props, locale, store seat, and streamed operation callbacks.
+ * @returns the section tree.
+ */
+export declare function BackupSection(props: BackupSectionProps): ReactNode;
+//# sourceMappingURL=BackupSection.d.ts.map

package/lib/types/client/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Settings Backup section plugin, browser half. Archive bytes use exact Host
+ * routes; preparation and restore state arrive as validated NDJSON progress
+ * lines, outside the unary RPC carrier.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type SettingsBackupKey } from './locales.ts';
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** Backup section copy. */
+        settingsBackup: SettingsBackupKey;
+    }
+}
+export declare const inject: string[];
+/** Register the Backup settings section and its exact-route transport callbacks. */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/locales.d.ts

@@ -0,0 +1,34 @@
+/** Settings Backup section dictionaries (zh product copy, en twin). */
+export declare const zh: {
+    readonly nav: "备份";
+    readonly title: "备份与恢复";
+    readonly desc: "把用户设置和数据导出为一个 zip 压缩包，或从备份压缩包恢复。";
+    readonly exportButton: "导出备份压缩包";
+    readonly importButton: "选择压缩包并导入";
+    readonly busyExport: "正在生成备份…";
+    readonly busyImport: "正在导入备份…";
+    readonly cancelButton: "取消";
+    readonly cancellingButton: "正在取消…";
+    readonly exportScan: "正在计算备份数据量…";
+    readonly exportCompress: "正在生成备份";
+    readonly exportProgressLabel: "备份生成进度";
+    readonly importUpload: "正在上传备份";
+    readonly importValidate: "正在校验备份完整性…";
+    readonly importRestore: "正在恢复备份";
+    readonly importReload: "正在加载会话与工作区…";
+    readonly importProgressLabel: "备份恢复进度";
+    readonly progressDetail: "数据较多时可能需要几分钟，请保持此页面打开。";
+    readonly exported: "备份已生成，浏览器已开始下载。";
+    readonly imported: "备份已导入。重新加载页面后，会话和工作区将使用恢复后的数据。";
+    readonly reloadButton: "重新加载页面";
+    readonly notBackup: "所选压缩包不是 DeepSeek Harness 备份文件。";
+    readonly unsafe: "备份压缩包包含不安全的条目路径。";
+    readonly exportFailed: "备份导出失败，请重试；若持续失败，请检查可用磁盘空间。";
+    readonly importFailed: "备份导入失败，请检查所选压缩包后重试。";
+    readonly warning: "备份压缩包包含 API 密钥等敏感信息，请妥善保管。";
+};
+/** English twin of the `zh` dictionary. */
+export declare const en: Record<SettingsBackupKey, string>;
+/** Dictionary keys of the `settingsBackup` locale namespace. */
+export type SettingsBackupKey = keyof typeof zh;
+//# sourceMappingURL=locales.d.ts.map

package/lib/types/client/store.d.ts

@@ -0,0 +1,20 @@
+/** Remount-surviving state for the Settings Backup slot registration. */
+import { type EngineStoreHandle } from '@deepseek-ai/dsh-client-store';
+import type { BackupErrorKey, BackupOperation, BackupSectionState, BackupStatusKey } from './types.ts';
+type BackupSectionActions = {
+    begin: (draft: BackupSectionState, operation: BackupOperation) => void;
+    progress: (draft: BackupSectionState, operation: BackupOperation) => void;
+    requestCancel: (draft: BackupSectionState) => void;
+    cancelled: (draft: BackupSectionState) => void;
+    complete: (draft: BackupSectionState, status: BackupStatusKey) => void;
+    fail: (draft: BackupSectionState, error: BackupErrorKey) => void;
+};
+/** Store handle shared by each remount of the root-scoped Backup section. */
+export type BackupSectionStore = EngineStoreHandle<BackupSectionState, BackupSectionActions>;
+/**
+ * Declare the Backup section operation and result state.
+ * @returns the root-scoped store handle.
+ */
+export declare function createBackupSectionStore(): BackupSectionStore;
+export {};
+//# sourceMappingURL=store.d.ts.map

package/lib/types/client/types.d.ts

@@ -0,0 +1,29 @@
+/** Browser presentation progress after parsing Host lines or upload events. */
+export type BackupSectionProgress = {
+    /** Phase without a measurable byte total. */
+    phase: 'scan' | 'validate' | 'reload';
+} | {
+    /** Phase with a stable byte total. */
+    phase: 'compress' | 'upload' | 'restore';
+    /** Bytes completed in the current phase. */
+    completedBytes: number;
+    /** Stable byte total for the current phase. */
+    totalBytes: number;
+};
+/** One active backup operation rendered by the Settings section. */
+export type BackupOperation = {
+    kind: 'export' | 'import';
+    progress: BackupSectionProgress;
+};
+/** Successful operation copy selected by the current locale. */
+export type BackupStatusKey = 'exported' | 'imported';
+/** Failed operation copy selected by the current locale. */
+export type BackupErrorKey = 'notBackup' | 'unsafe' | 'exportFailed' | 'importFailed';
+/** Remount-surviving presentation state owned by the Backup slot registration. */
+export type BackupSectionState = {
+    operation: BackupOperation | null;
+    status: BackupStatusKey | null;
+    error: BackupErrorKey | null;
+    cancelling: boolean;
+};
+//# sourceMappingURL=types.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,19 @@
+/** Full-stack Plus user-data Backup Host plugin. */
+import Schema from '@deepseek-ai/schemastery';
+import { type BackupHostContext } from './routes.ts';
+export declare const name = "plus-backup";
+export declare const inject: string[];
+/** Backup Host resource policy. */
+export interface Config {
+    /** Maximum uploaded ZIP bytes written to Host disk. @default 2147483648 */
+    maxUploadBytes?: number;
+}
+/** Validate Backup Host resource policy. */
+export declare const Config: Schema<Config>;
+/**
+ * Register authenticated archive routes against a file-backed DSH home.
+ * @param ctx - Host services plus the temporary patched Workspace restore operation.
+ * @param config - Upload resource policy resolved by Cordis.
+ */
+export declare function apply(ctx: BackupHostContext, config?: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,11 @@
+/** Package invariant companion for `@sparkelf/dsh-plugin-backup`. */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "plus-backup-invariant";
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Host context carrying the invariant registry.
+ * @returns the registration disposer.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/protocol.d.ts

@@ -0,0 +1,32 @@
+/** Host progress and terminal records for Plus user-data Backup routes. */
+/** Progress without a stable byte total while scanning, validating, or reloading. */
+type BackupOpenProgress = {
+    phase: 'scan' | 'validate' | 'reload';
+};
+/** Progress with a stable byte total while compressing or restoring. */
+type BackupMeasuredProgress = {
+    phase: 'compress' | 'restore';
+    completedBytes: number;
+    totalBytes: number;
+};
+/** Host-authored progress emitted by one Backup operation. */
+export type BackupHostProgress = BackupOpenProgress | BackupMeasuredProgress;
+/** Ordered progress writer; archive work waits for response backpressure. */
+export type BackupProgressReporter = (progress: BackupHostProgress) => Promise<void>;
+/** One NDJSON progress or terminal line sent to the Client. */
+export type BackupProgressLine = {
+    type: 'progress';
+    progress: BackupHostProgress;
+} | {
+    type: 'export-ready';
+    downloadUrl: string;
+    entries: number;
+} | {
+    type: 'import-complete';
+    entries: number;
+} | {
+    type: 'error';
+    message: string;
+};
+export {};
+//# sourceMappingURL=protocol.d.ts.map

package/lib/types/routes.d.ts

@@ -0,0 +1,20 @@
+/** Authenticated Host routes for streamed user-data Backup export and import. */
+import type { Context } from '@deepseek-ai/cordis';
+/** Official Host context plus the one temporary Workspace operation supplied by the source patch. */
+export type BackupHostContext = Context & {
+    workspaceRegistry: Context['workspaceRegistry'] & {
+        withStorageRestore<T>(restore: () => Promise<T>): Promise<T>;
+    };
+};
+/** Backup route resource policy. */
+export interface BackupRouteConfig {
+    maxUploadBytes: number;
+}
+/**
+ * Register the complete authenticated Backup route set and its temp-file lifecycle.
+ * @param ctx - Host services and the patched Workspace restore operation.
+ * @param config - Upload resource policy.
+ * @param dshHome - File-backed DSH home whose user data is archived.
+ */
+export declare function registerBackupRoutes(ctx: BackupHostContext, config: BackupRouteConfig, dshHome: string): void;
+//# sourceMappingURL=routes.d.ts.map

package/package.json

@@ -0,0 +1,83 @@
+{
+  "dependencies": {
+    "@deepseek-ai/schemastery": ">=3.18.1",
+    "fflate": "^0.8.2",
+    "yauzl": "^3.2.0"
+  },
+  "description": "Full-stack Plus user-data Backup plugin with streamed Host archive routes and Settings UI",
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-client-locale": "^0.1.2-alpha.1",
+    "@deepseek-ai/dsh-client-store": "^0.1.2-alpha.1",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.2-alpha.1",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.2-alpha.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.2-alpha.1",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.2-alpha.1",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.1",
+    "@deepseek-ai/dsh-settings": "^0.1.2-alpha.1",
+    "@deepseek-ai/dsh-workspace": "^0.1.2-alpha.1",
+    "@types/react": "~18.3.1",
+    "@types/yauzl": "^2.10.3",
+    "react": "^18.2.0"
+  },
+  "dsh": {
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-renderer"
+      ],
+      "platform": "web"
+    }
+  },
+  "exports": {
+    ".": {
+      "default": "./lib/index.js",
+      "types": "./lib/types/index.d.ts"
+    },
+    "./client": {
+      "default": "./lib/client.js",
+      "types": "./lib/types/client/index.d.ts"
+    },
+    "./invariant": {
+      "default": "./lib/invariant.js",
+      "types": "./lib/types/invariant.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "main": "lib/index.js",
+  "name": "@sparkelf/dsh-plugin-backup",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=4.0.1",
+    "@deepseek-ai/dsh-client-locale": ">=0.1.2-alpha.1",
+    "@deepseek-ai/dsh-client-ui-renderer": ">=0.1.2-alpha.1",
+    "@deepseek-ai/dsh-client-ui-settings": ">=0.1.2-alpha.1",
+    "@deepseek-ai/dsh-client-ui-slots": ">=0.1.2-alpha.1",
+    "@deepseek-ai/dsh-host-webserver": ">=0.1.2-alpha.1",
+    "@deepseek-ai/dsh-invariants": ">=0.1.2-alpha.1",
+    "@deepseek-ai/dsh-settings": ">=0.1.2-alpha.1",
+    "@deepseek-ai/dsh-workspace": ">=0.1.2-alpha.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "directory": "packages/plus/backup",
+    "type": "git",
+    "url": "git+https://github.com/SparkElf/deepseek-harness-plus.git"
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  },
+  "type": "module",
+  "types": "lib/types/index.d.ts",
+  "version": "0.1.0-rc.10"
+}