@wildusk/dsh-backup 0.1.0

package/README.md

@@ -0,0 +1,54 @@
+# @wildusk/dsh-backup
+
+DeepSeek Harness plugin backup. Archives are written to `~/.dsh-backup`.
+
+Repository: https://github.com/usertoandy/dsh-backup.git
+
+## Commands
+
+| Command | Function |
+| --- | --- |
+| `/backup` | Archive the DSH home to `~/.dsh-backup/dsh-backup-<timestamp>.tar.gz` and report the archive path and size. |
+| `/backup-list` | List the existing archives in `~/.dsh-backup` (number, filename, size, date). |
+| `/backup-restore` | Ask (via the harness question UI) which backup to restore and how, then extract it into the DSH home. |
+
+### Restore modes
+
+The confirm question offers the original tool's three answers:
+
+- `yes` — extract over the current files; files not in the backup are kept.
+- `clean` — empty the DSH home first, then extract (exact restore of the backup).
+  Refused when the target resolves to `/` or the user's home directory.
+- `no` — cancel the restore.
+
+After a restore you may need to restart any running `dsh` processes.
+
+## Install
+
+The host loads `src/index.ts` directly (no build step).
+
+1. Download from GitHub:
+
+```sh
+git clone https://github.com/usertoandy/dsh-backup.git
+```
+
+2. Register the plugin with a profile (the bundles list is updated
+   automatically by `dsh plugin add`):
+
+```sh
+dsh plugin --profile web add ./dsh-backup
+```
+
+Restart `dsh web` afterwards; `/backup`, `/backup-list` and `/backup-restore`
+then appear in the command palette.
+
+At runtime the plugin uses the host-provided `commands` and `userQuestions`
+services plus `tar` on the PATH.
+
+## Files
+
+- `src/index.ts` — plugin entry: `name` / `inject` / `apply`.
+- `src/commands.ts` — the three command handlers and their output text.
+- `src/backup-core.ts` — timestamped tar.gz creation, listing and guarded
+  restore (asynchronous, abort-aware).

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+# @wildusk/dsh-backup bundle patch: one host row over the profile.
+- insert:
+    - id: '@wildusk/dsh-backup'
+      name: '@wildusk/dsh-backup'

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@wildusk/dsh-backup",
+  "version": "0.1.0",
+  "description": "DeepSeek Harness plugin: /backup, /backup-list and /backup-restore commands to back up, list and restore the DSH home directory. DeepSeek Harness 备份插件：一键备份 DSH 主目录（~/.dsh）为时间戳 tar.gz 归档、查看历史备份并恢复。",
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "cordis.patch.yml"
+  ],
+  "scripts": {
+    "test": "tsx tests/core.test.mjs"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dshhub": {
+    "schemaVersion": 1,
+    "displayName": "@wildusk/dsh-backup",
+    "summary": "DeepSeek Harness 备份插件：/backup 一键将 DSH 主目录（~/.dsh）备份为时间戳 tar.gz 归档，/backup-list 查看历史备份，/backup-restore 交互式恢复到指定备份。",
+    "categories": [
+      "备份"
+    ],
+    "surfaces": [
+      "host"
+    ]
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "dsh-plugin",
+    "cordis",
+    "backup",
+    "restore"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-commands": ">=0.1.2-alpha.4",
+    "@deepseek-ai/dsh-user-questions": ">=0.1.2-alpha.4"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-commands": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-user-questions": "^0.1.2-rc.1",
+    "@types/node": "^24",
+    "tsx": "^4.19.0"
+  }
+}

package/src/backup-core.ts

@@ -0,0 +1,176 @@
+/**
+ * Core backup/list/restore logic: timestamped `tar -czf` archives of the DSH home under the backup directory,
+ * a newest-first listing, and guarded extraction back into the DSH home.
+ *
+ * Unlike the original CLI tool this runs inside the harness host process, so
+ * every operation is asynchronous, `tar` output is captured instead of
+ * inherited, and long-running work honours an abort signal.
+ *
+ * @module @wildusk/dsh-backup/backup-core
+ */
+
+import { spawn } from 'child_process'
+import { existsSync } from 'fs'
+import { mkdir, readdir, rm, stat } from 'fs/promises'
+import * as os from 'os'
+import * as path from 'path'
+
+/** Filename shape shared by every archive this tool writes. */
+export const BACKUP_PATTERN = /^dsh-backup-.+\.tar\.gz$/u
+
+/** Most recent backups offered as selectable options in the restore dialog. */
+export const RESTORE_CHOICES = 10
+
+/** One existing backup archive. */
+export interface BackupEntry {
+  /** Archive file name inside the backup directory. */
+  readonly file: string
+  /** Absolute archive path. */
+  readonly path: string
+  /** File size in MB with two decimals. */
+  readonly sizeMB: string
+  /** Modification time as `YYYY-MM-DD HH:MM:SS`. */
+  readonly date: string
+}
+
+/** Resolved directories this plugin operates on. */
+export interface BackupPaths {
+  /** DSH home directory being backed up and restored. */
+  readonly dshHome: string
+  /** Directory receiving the `dsh-backup-*.tar.gz` archives. */
+  readonly backupDir: string
+}
+
+/** Domain error whose message is safe to show to the user. */
+export class BackupError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'BackupError'
+  }
+}
+
+/** Raised when the invocation signal aborted the pending tar work. */
+export class BackupCancelledError extends BackupError {
+  constructor() {
+    super('Operation cancelled.')
+    this.name = 'BackupCancelledError'
+  }
+}
+
+/** Restore modes mirroring the original tool's yes/clean answer. */
+export type RestoreMode = 'yes' | 'clean'
+
+/** Local-time timestamp in the shared `YYYY-MM-DD_HH-MM-SS` format. */
+export function getTimestamp(): string {
+  const date = new Date()
+  const timezoneOffsetMinutes = date.getTimezoneOffset()
+  const offsetMs = timezoneOffsetMinutes * 60 * 1000
+  const localAsUtc = new Date(date.getTime() - offsetMs)
+  return localAsUtc.toISOString()
+    .replace(/[:.]/gu, '-')
+    .replace('T', '_')
+    .slice(0, 19)
+}
+
+/** Human-readable MB size with two decimals. */
+export function formatSizeMB(size: number): string {
+  return (size / 1024 / 1024).toFixed(2)
+}
+
+/** List the backup directory, newest archive first; empty when it does not exist. */
+export async function listBackups(backupDir: string): Promise<BackupEntry[]> {
+  if (!existsSync(backupDir)) return []
+  const files = (await readdir(backupDir))
+    .filter(file => BACKUP_PATTERN.test(file))
+    .sort()
+    .reverse()
+  const entries: BackupEntry[] = []
+  for (const file of files) {
+    const filePath = path.join(backupDir, file)
+    const stats = await stat(filePath)
+    entries.push({
+      file,
+      path: filePath,
+      sizeMB: formatSizeMB(stats.size),
+      date: stats.mtime.toISOString().replace('T', ' ').slice(0, 19),
+    })
+  }
+  return entries
+}
+
+/** Create a timestamped tar.gz archive of the DSH home inside the backup directory. */
+export async function createBackupArchive(paths: BackupPaths, signal: AbortSignal): Promise<BackupEntry> {
+  if (!existsSync(paths.dshHome)) {
+    throw new BackupError(`DSH_HOME directory does not exist: ${paths.dshHome}`)
+  }
+  await mkdir(paths.backupDir, { recursive: true })
+  const file = `dsh-backup-${getTimestamp()}.tar.gz`
+  const archivePath = path.join(paths.backupDir, file)
+  await runTar(['-czf', archivePath, '-C', paths.dshHome, '.'], signal)
+  const stats = await stat(archivePath)
+  return {
+    file,
+    path: archivePath,
+    sizeMB: formatSizeMB(stats.size),
+    date: stats.mtime.toISOString().replace('T', ' ').slice(0, 19),
+  }
+}
+
+/** Extract a backup archive into the DSH home; `clean` empties the target first. */
+export async function restoreBackupArchive(
+  archivePath: string,
+  paths: BackupPaths,
+  mode: RestoreMode,
+  signal: AbortSignal,
+): Promise<void> {
+  if (!existsSync(archivePath)) {
+    throw new BackupError(`Backup archive does not exist: ${archivePath}`)
+  }
+  if (mode === 'clean') {
+    // Clean mode must remove files absent from the archive, so wipe the target first.
+    const target = path.resolve(paths.dshHome)
+    if (target === '/' || target === path.resolve(os.homedir())) {
+      throw new BackupError(`Refusing to clean unsafe DSH_HOME: ${paths.dshHome}`)
+    }
+    await rm(paths.dshHome, { recursive: true, force: true })
+  }
+  await mkdir(paths.dshHome, { recursive: true })
+  await runTar(['-xzf', archivePath, '-C', paths.dshHome], signal)
+}
+
+/** Run one tar invocation, killing the child when the signal fires. */
+function runTar(args: readonly string[], signal: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) {
+      reject(new BackupCancelledError())
+      return
+    }
+    const child = spawn('tar', [...args], { stdio: ['ignore', 'ignore', 'pipe'] })
+    let stderr = ''
+    child.stderr?.on('data', (chunk: Buffer) => {
+      stderr += chunk.toString()
+    })
+    const onAbort = (): void => {
+      child.kill('SIGTERM')
+    }
+    const cleanup = (): void => {
+      signal.removeEventListener('abort', onAbort)
+    }
+    signal.addEventListener('abort', onAbort, { once: true })
+    child.on('error', error => {
+      cleanup()
+      reject(new BackupError(`Failed to run tar: ${error.message}`))
+    })
+    child.on('close', code => {
+      cleanup()
+      if (signal.aborted) {
+        reject(new BackupCancelledError())
+      } else if (code === 0) {
+        resolve()
+      } else {
+        const detail = stderr.trim()
+        reject(new BackupError(`tar exited with code ${code}${detail === '' ? '' : `: ${detail}`}`))
+      }
+    })
+  })
+}

package/src/commands.ts

@@ -0,0 +1,271 @@
+/**
+ * Slash-command handlers for /backup, /backup-list and /backup-restore.
+ *
+ * Output follows the harness's built-in command conventions: handlers return
+ * multi-line plain text rendered in the command card, argument errors carry a
+ * `Usage:` trailer, operational events go to the cordis logger with a
+ * `dsh-backup:` prefix, and the restore selection/confirmation prompts use the
+ * user-questions UI — the chat equivalent of the original tool's readline flow.
+ *
+ * @module @wildusk/dsh-backup/commands
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type { CommandInvocation, CommandResult } from '@deepseek-ai/dsh-commands'
+import type {
+  AskUserQuestionAnswerItem,
+  AskUserQuestionItem,
+} from '@deepseek-ai/dsh-user-questions'
+import {
+  type BackupEntry,
+  BackupCancelledError,
+  type BackupPaths,
+  BackupError,
+  RESTORE_CHOICES,
+  type RestoreMode,
+  createBackupArchive,
+  listBackups,
+  restoreBackupArchive,
+} from './backup-core.ts'
+
+const USAGE_BACKUP = 'Usage: /backup'
+const USAGE_LIST = 'Usage: /backup-list'
+const USAGE_RESTORE = 'Usage: /backup-restore'
+
+/** Register the three commands for the composed command adapter. */
+export function registerBackupCommands(ctx: Context, paths: BackupPaths): void {
+  ctx.effect(() => ctx.commands.register({
+    name: 'backup',
+    description: 'back up the DSH home directory to a timestamped tar.gz archive',
+    handler: invocation => runBackupCommand(ctx, paths, invocation),
+  }), 'dsh-backup: /backup')
+  ctx.effect(() => ctx.commands.register({
+    name: 'backup-list',
+    description: 'list the existing dsh-backup archives',
+    handler: invocation => runBackupListCommand(ctx, paths, invocation),
+  }), 'dsh-backup: /backup-list')
+  ctx.effect(() => ctx.commands.register({
+    name: 'backup-restore',
+    description: 'restore the DSH home directory from a backup archive (asks which one and confirms)',
+    handler: invocation => runBackupRestoreCommand(ctx, paths, invocation),
+  }), 'dsh-backup: /backup-restore')
+}
+
+/** `/backup`: archive the DSH home into the backup directory. */
+async function runBackupCommand(
+  ctx: Context,
+  paths: BackupPaths,
+  invocation: CommandInvocation,
+): Promise<CommandResult> {
+  if (invocation.rawInput.trim() !== '') {
+    return { kind: 'error', text: `The /backup command takes no arguments. ${USAGE_BACKUP}` }
+  }
+  try {
+    const entry = await createBackupArchive(paths, invocation.signal)
+    ctx.logger.info(`dsh-backup: created ${entry.path} (${entry.sizeMB} MB)`)
+    return {
+      kind: 'success',
+      text: [
+        'Backup completed.',
+        `Source: ${paths.dshHome}`,
+        `Archive: ${entry.path}`,
+        `Size: ${entry.sizeMB} MB`,
+        '',
+        'Tip: /backup-list shows all backups; /backup-restore restores one.',
+      ].join('\n'),
+    }
+  } catch (error: unknown) {
+    return settleFailure(ctx, 'Backup', error)
+  }
+}
+
+/** `/backup-list`: render the backup directory as the original tool's table. */
+async function runBackupListCommand(
+  ctx: Context,
+  paths: BackupPaths,
+  invocation: CommandInvocation,
+): Promise<CommandResult> {
+  if (invocation.rawInput.trim() !== '') {
+    return { kind: 'error', text: `The /backup-list command takes no arguments. ${USAGE_LIST}` }
+  }
+  let backups: BackupEntry[]
+  try {
+    backups = await listBackups(paths.backupDir)
+  } catch (error: unknown) {
+    return settleFailure(ctx, 'List', error)
+  }
+  if (backups.length === 0) {
+    return {
+      kind: 'success',
+      text: `No backups found in ${paths.backupDir}.\nCreate one with /backup.`,
+    }
+  }
+  const lines = [
+    `Existing backups in ${paths.backupDir}: ${backups.length}`,
+    '',
+    '  #  Filename                                    Size       Date',
+    '  ── ─────────────────────────────────────────── ────────── ────────────────────',
+  ]
+  backups.forEach((backup, index) => {
+    lines.push(`  ${String(index + 1).padStart(2)} ${backup.file.padEnd(43)} ${backup.sizeMB.padStart(6)} MB  ${backup.date}`)
+  })
+  lines.push('', `  Total: ${backups.length} backup(s)`)
+  return { kind: 'success', text: lines.join('\n') }
+}
+
+/** `/backup-restore`: pick a backup and confirm through the user-questions UI. */
+async function runBackupRestoreCommand(
+  ctx: Context,
+  paths: BackupPaths,
+  invocation: CommandInvocation,
+): Promise<CommandResult> {
+  if (invocation.rawInput.trim() !== '') {
+    return { kind: 'error', text: `The /backup-restore command takes no arguments. ${USAGE_RESTORE}` }
+  }
+  let backups: BackupEntry[]
+  try {
+    backups = await listBackups(paths.backupDir)
+  } catch (error: unknown) {
+    return settleFailure(ctx, 'Restore', error)
+  }
+  if (backups.length === 0) {
+    return {
+      kind: 'error',
+      text: `No backups found to restore in ${paths.backupDir}.\nCreate one with /backup.`,
+    }
+  }
+  const choice = await askRestoreChoice(ctx, paths, backups, invocation)
+  if (choice === undefined) return { kind: 'success', text: 'Restore cancelled.' }
+  try {
+    await restoreBackupArchive(choice.entry.path, paths, choice.mode, invocation.signal)
+  } catch (error: unknown) {
+    return settleFailure(ctx, 'Restore', error)
+  }
+  ctx.logger.info(
+    `dsh-backup: restored ${choice.entry.path} (${choice.mode}) into ${paths.dshHome}`)
+  return {
+    kind: 'success',
+    text: [
+      'Restore completed successfully.',
+      `Archive: ${choice.entry.path}`,
+      `Target: ${paths.dshHome}`,
+      `Mode: ${choice.mode === 'clean'
+        ? 'clean — DSH_HOME was emptied first, the backup is restored exactly'
+        : 'yes — extracted over the current files; files not in the backup are kept'}`,
+      '',
+      'You may need to restart any running dsh processes.',
+    ].join('\n'),
+  }
+}
+
+/** The resolved restore choice, or `undefined` when the user cancelled. */
+type RestoreChoice = { readonly entry: BackupEntry; readonly mode: RestoreMode }
+
+/**
+ * Ask which backup to restore and how, mirroring the original tool's
+ * selection prompt and yes/clean/no confirmation in one dialog.
+ *
+ * @returns The resolved choice, or `undefined` for a cancel/decline answer.
+ * @throws {BackupError} when the dialog fails or the selection is unusable.
+ */
+async function askRestoreChoice(
+  ctx: Context,
+  paths: BackupPaths,
+  backups: readonly BackupEntry[],
+  invocation: CommandInvocation,
+): Promise<RestoreChoice | undefined> {
+  const questions: AskUserQuestionItem[] = [
+    {
+      id: 'backup',
+      header: 'Backup',
+      question: `Which backup do you want to restore into ${paths.dshHome}?`,
+      options: backups.slice(0, RESTORE_CHOICES).map((backup, index) => ({
+        label: `#${index + 1} ${backup.file}`,
+        description: `${backup.sizeMB} MB, ${backup.date}`,
+      })),
+    },
+    {
+      id: 'confirm',
+      header: 'Confirm',
+      question: 'Are you sure? This will overwrite the current DSH_HOME directory.',
+      detail: [
+        `Target: ${paths.dshHome}`,
+        '',
+        'yes   - extract over current files (files not in the backup are kept)',
+        'clean - empty DSH_HOME first, then extract (exact restore of the backup)',
+        'no    - cancel the restore',
+      ].join('\n'),
+      options: [
+        { label: 'yes', description: 'extract over current files' },
+        { label: 'clean', description: 'empty DSH_HOME first, then extract' },
+        { label: 'no', description: 'cancel the restore' },
+      ],
+    },
+  ]
+  let answer: { readonly answers: readonly AskUserQuestionAnswerItem[] }
+  try {
+    answer = await ctx.userQuestions.ask({
+      questions,
+      agent: invocation.agent,
+      signal: invocation.signal,
+    })
+  } catch (error: unknown) {
+    if (isCancelledAsk(error)) return undefined
+    // No answerer accepted the dialog (e.g. a headless context): say why.
+    ctx.logger.error(`dsh-backup: restore dialog failed: ${errorMessage(error)}`)
+    throw new BackupError(`Restore dialog failed: ${errorMessage(error)}`)
+  }
+  const mode = normalizeMode(answer.answers.find(item => item.id === 'confirm')?.selected[0])
+  if (mode === undefined) return undefined
+  const entry = resolveBackupSelection(backups, answer.answers.find(item => item.id === 'backup'))
+  if (entry === undefined) {
+    throw new BackupError(`Invalid backup selection. ${USAGE_RESTORE}`)
+  }
+  return { entry, mode }
+}
+
+/** Resolve the first question's answer back to a listed archive. */
+function resolveBackupSelection(
+  backups: readonly BackupEntry[],
+  answer: AskUserQuestionAnswerItem | undefined,
+): BackupEntry | undefined {
+  const custom = answer?.custom?.trim() ?? ''
+  if (custom !== '') {
+    const numeric = /^(\d+)$/u.exec(custom)
+    if (numeric !== null) {
+      const index = Number(numeric[1]) - 1
+      return index >= 0 && index < backups.length ? backups[index] : undefined
+    }
+    return backups.find(backup => backup.file === custom || backup.path === custom)
+  }
+  const label = answer?.selected[0]?.trim() ?? ''
+  const numbered = /^#\d+\s+(.+)$/u.exec(label)
+  const file = numbered?.[1]?.trim() ?? label
+  if (file === '') return undefined
+  return backups.find(backup => backup.file === file || backup.path === file)
+}
+
+/** Normalize the confirm answer; anything but yes/clean declines the restore. */
+function normalizeMode(label: string | undefined): RestoreMode | undefined {
+  const mode = label?.trim().toLowerCase()
+  return mode === 'yes' || mode === 'clean' ? mode : undefined
+}
+
+/** Whether the user-questions dialog was cancelled by the user or the signal. */
+function isCancelledAsk(error: unknown): boolean {
+  return (error as { code?: unknown } | null | undefined)?.code === 'ASK_ABORTED'
+}
+
+/** Render one settled failure; cancelled work is a normal outcome, not an error. */
+function settleFailure(ctx: Context, action: string, error: unknown): CommandResult {
+  if (error instanceof BackupCancelledError) {
+    return { kind: 'success', text: `${action} cancelled.` }
+  }
+  const message = errorMessage(error)
+  ctx.logger.error(`dsh-backup: ${action.toLowerCase()} failed: ${message}`)
+  return { kind: 'error', text: `${action} failed: ${message}` }
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}

package/src/index.ts

@@ -0,0 +1,34 @@
+/**
+ * dsh-backup: /backup, /backup-list and /backup-restore slash commands that
+ * back up, list and restore the DSH home directory; output follows the
+ * harness's built-in command conventions and the restore prompts use the
+ * user-questions UI.
+ *
+ * @module @wildusk/dsh-backup
+ */
+
+import * as os from 'os'
+import * as path from 'path'
+import type { Context } from '@deepseek-ai/cordis'
+import type { BackupPaths } from './backup-core.ts'
+import { registerBackupCommands } from './commands.ts'
+
+export const name = '@wildusk/dsh-backup'
+
+export const inject = ['commands', 'userQuestions']
+
+export function apply(ctx: Context): void {
+  const paths: BackupPaths = {
+    dshHome: firstNonEmpty(process.env.DSH_HOME, path.join(os.homedir(), '.dsh')),
+    backupDir: path.join(os.homedir(), '.dsh-backup'),
+  }
+  registerBackupCommands(ctx, paths)
+}
+
+function firstNonEmpty(...values: readonly (string | undefined)[]): string {
+  for (const value of values) {
+    const trimmed = value?.trim()
+    if (trimmed !== undefined && trimmed !== '') return trimmed
+  }
+  return path.join(os.homedir(), '.dsh')
+}