dsh-taskboard 0.2.2 → 0.4.0

package/src/host/routes.ts

@@ -10,25 +10,34 @@
  * @module dsh-taskboard/host/routes
  */
 import type { IncomingMessage, ServerResponse } from 'node:http'
+import { readdir, rm } from 'node:fs/promises'
+import { join } from 'node:path'
 import type { Context } from '@deepseek-ai/cordis'
 // Type-only: pulls the webServer Context merge (ctx.webServer).
 import type {} from '@deepseek-ai/dsh-host-webserver'
 import {
+  asIsolation,
   asStatus,
   asUrgency,
   canTransition,
+  checklistFromTexts,
   newCommentId,
   newTaskId,
   normalizeBody,
+  normalizeChecklist,
   normalizeExecution,
   normalizeModel,
   normalizePrompt,
   normalizeTitle,
   summarize,
   syncClaim,
+  validateLedgerImport,
   type TaskModel,
   type TaskRecord,
 } from '../shared/protocol.ts'
+import { WORKTREE_DIR, worktreePathOf, type GitFace } from './git.ts'
+import type { TaskTemplate } from '../shared/api.ts'
+import type { TemplateStore } from './templates.ts'
 import { ROUTE_PREFIX, SSE_PATH, type ApiFail, type ApiResult } from '../shared/api.ts'
 import type { TaskStore } from './store.ts'
 import type { WorkspaceFace } from './tools.ts'
@@ -36,6 +45,9 @@ import type { WorkspaceFace } from './tools.ts'
 /** Heartbeat cadence for the SSE stream. */
 const HEARTBEAT_MS = 20_000
 
+/** How long a workspace git-detection result stays cached (fail-soft). */
+const GIT_DETECT_TTL_MS = 60_000
+
 /** The workspaces face routes need (same narrow shape as tools). */
 export type RoutesWorkspaceFace = WorkspaceFace
 
@@ -44,8 +56,8 @@ export interface TaskboardRoutesOptions {
   store: TaskStore
   workspaces: RoutesWorkspaceFace
   now: () => number
-  /** Manual-run hook (the execution service); absent → 501. */
-  run?: (taskId: string) => Promise<{ ok: true; executionId: string; sessionId: string } | { ok: false; error: string }>
+  /** Manual-run hook (the execution service); absent → 501. Options carry `reuseWorktree` (续跑). */
+  run?: (taskId: string, options?: { reuseWorktree?: boolean }) => Promise<{ ok: true; executionId: string; sessionId: string } | { ok: false; error: string }>
   /** Cancel hook (the execution service); absent → 501. */
   cancel?: (taskId: string) => Promise<{ ok: true; executionId: string } | { ok: false; error: string }>
   /**
@@ -53,6 +65,47 @@ export interface TaskboardRoutesOptions {
    * advisory validation of pinned models; undefined = runtime unavailable.
    */
   modelProviders?: () => string[] | undefined
+  /** Git face for worktree actions + workspace git detection; absent → 501 on git actions. */
+  git?: GitFace
+  /** Task-template store (0.4.0); absent → 501 on template actions. */
+  templates?: TemplateStore
+}
+
+/** Validate a template's task spec (routes-side, unknown → invalid_input). */
+function normalizeTemplateSpec(raw: unknown): TaskTemplate['task'] {
+  if (typeof raw !== 'object' || raw === null) throw new Error('Error: invalid_input: task must be an object')
+  const e = raw as Record<string, unknown>
+  const spec: TaskTemplate['task'] = {}
+  const str = (key: string): string | undefined => {
+    const v = e[key]
+    if (v === undefined) return undefined
+    if (typeof v !== 'string') throw new Error(`Error: invalid_input: task.${key} must be a string`)
+    return v
+  }
+  const title = str('title')
+  const description = str('description')
+  const prompt = str('prompt')
+  const urgency = str('urgency')
+  const isolation = str('isolation')
+  const presetId = str('presetId')
+  if (title !== undefined) spec.title = normalizeTitle(title)
+  if (description !== undefined) spec.description = description
+  if (prompt !== undefined) spec.prompt = normalizePrompt(prompt)
+  if (urgency !== undefined) spec.urgency = asUrgency(urgency)
+  if (isolation !== undefined) spec.isolation = asIsolation(isolation)
+  if (presetId !== undefined && presetId.trim().length > 0) spec.presetId = presetId.trim()
+  if (e.execution !== undefined) {
+    spec.execution = normalizeExecution(e.execution as { mode?: string; cron?: string }, Date.now())
+  }
+  if (e.model !== undefined) spec.model = normalizeModel(e.model)
+  if (e.checklist !== undefined) {
+    if (!Array.isArray(e.checklist) || e.checklist.some(c => typeof c !== 'string')) {
+      throw new Error('Error: invalid_input: task.checklist must be an array of strings')
+    }
+    checklistFromTexts(e.checklist as string[]) // validates count + texts
+    spec.checklist = e.checklist as string[]
+  }
+  return spec
 }
 
 /** Validate a pinned model: structural check always, provider route when known. */
@@ -108,6 +161,12 @@ function num(body: Record<string, unknown>, key: string): number | undefined | n
   return typeof v === 'number' && Number.isFinite(v) ? v : null
 }
 
+/** Normalize an agent preset id: trimmed, non-empty; empty string → undefined. */
+function normalizePresetId(raw: string | null): string | undefined {
+  const t = (raw ?? '').trim()
+  return t.length === 0 ? undefined : t
+}
+
 /** Map a thrown domain error to the envelope. */
 function toFail(error: unknown): { res: ApiFail; status: number } {
   const message = error instanceof Error ? error.message : String(error)
@@ -137,6 +196,72 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
   }
   store.subscribe(broadcast)
 
+  // Workspace git detection, TTL-cached and fail-soft (false on any error):
+  // feeds the create-form isolation toggle and the diagnostics panel.
+  const gitCache = new Map<string, { value: boolean; at: number }>()
+  const gitHinted = new Set<string>()
+
+  /** Whether <root>/.gitignore (missing file counts as missing) ignores our worktree dir. */
+  const gitignoreMissing = async (path: string): Promise<boolean> => {
+    try {
+      const { readFile } = await import('node:fs/promises')
+      const ignore = await readFile(join(path, '.gitignore'), 'utf8')
+      return !ignore.split('\n').some(l => {
+        const t = l.trim().replace(/\/+$/, '')
+        return t === WORKTREE_DIR || t === `/${WORKTREE_DIR}`
+      })
+    } catch {
+      return true // no .gitignore at all (or unreadable) → suggest creating one
+    }
+  }
+
+  const gitAvailable = async (path: string): Promise<boolean> => {
+    if (options.git === undefined) return false
+    const hit = gitCache.get(path)
+    if (hit !== undefined && options.now() - hit.at < GIT_DETECT_TTL_MS) return hit.value
+    let value = false
+    try {
+      value = await options.git.detect(path)
+    } catch { /* fail-soft → false */ }
+    gitCache.set(path, { value, at: options.now() })
+    // gitignore 建议 (plan §3.2): suggest (never write) ignoring our
+    // worktree directory, once per workspace per host run.
+    if (value && !gitHinted.has(path)) {
+      gitHinted.add(path)
+      if (await gitignoreMissing(path)) {
+        console.info(`[dsh-taskboard] 建议在 ${path}/.gitignore 加入一行 ${WORKTREE_DIR}/ 以隐藏任务 worktree 目录（不会自动修改）`)
+      }
+    }
+    return value
+  }
+
+  /** List orphan worktree dirs: entries under <ws>/.dsh-worktrees owned by no ledger task. */
+  const listOrphanWorktrees = async (): Promise<Array<{ workspaceId: string; workspacePath: string; taskId: string; path: string }>> => {
+    const orphans: Array<{ workspaceId: string; workspacePath: string; taskId: string; path: string }> = []
+    const known = new Set(store.snapshot().tasks.map(t => t.id))
+    for (const ws of workspaces.list()) {
+      let entries: string[] = []
+      try {
+        const dirents = await readdir(join(ws.path, WORKTREE_DIR), { withFileTypes: true })
+        entries = dirents.filter(e => e.isDirectory()).map(e => e.name)
+      } catch { /* no worktrees dir → nothing to do */ }
+      for (const taskId of entries) {
+        if (!known.has(taskId)) orphans.push({ workspaceId: ws.id, workspacePath: ws.path, taskId, path: worktreePathOf(ws.path, taskId) })
+      }
+    }
+    return orphans
+  }
+
+  /** Git-enabled workspaces whose .gitignore does not cover the worktree dir. */
+  const listGitignoreSuggestions = async (): Promise<Array<{ workspaceId: string; workspacePath: string }>> => {
+    const suggestions: Array<{ workspaceId: string; workspacePath: string }> = []
+    for (const ws of workspaces.list()) {
+      if (!(await gitAvailable(ws.path))) continue
+      if (await gitignoreMissing(ws.path)) suggestions.push({ workspaceId: ws.id, workspacePath: ws.path })
+    }
+    return suggestions
+  }
+
   const handler = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
     try {
       const url = new URL(req.url ?? '/', 'http://x')
@@ -150,9 +275,86 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
           return
         }
         if (pathname === `${ROUTE_PREFIX}/workspaces`) {
-          json(res, { ok: true, value: workspaces.list() })
+          const list = workspaces.list()
+          const flags = await Promise.all(list.map(ws => gitAvailable(ws.path)))
+          json(res, {
+            ok: true,
+            value: list.map((ws, i) => ({ ...ws, sessionCount: 0, gitAvailable: flags[i] })),
+          })
+          return
+        }
+        if (pathname === `${ROUTE_PREFIX}/diagnostics`) {
+          const ledger = store.snapshot()
+          let staleRunning = 0
+          for (const t of ledger.tasks) {
+            for (const e of t.executions) if (e.outcome === 'running') staleRunning += 1
+          }
+          json(res, {
+            ok: true,
+            value: {
+              revision: ledger.revision,
+              tasks: ledger.tasks.length,
+              staleRunning,
+              orphanWorktrees: await listOrphanWorktrees(),
+              gitIgnoreSuggestions: await listGitignoreSuggestions(),
+            },
+          })
           return
         }
+        // Diff viewer (0.4.0): read-only git show/diff for one execution's
+        // commit or changed path. Prefers the live worktree (uncommitted
+        // view), falls back to the main repo.
+        const diffMatch = pathname.match(new RegExp(`^${ROUTE_PREFIX}/tasks/([^/]+)/diff$`))
+        if (diffMatch !== null) {
+          try {
+            if (options.git === undefined) {
+              const f = fail('invalid_input', 'git integration unavailable')
+              json(res, f.res, 501)
+              return
+            }
+            const task = store.get(diffMatch[1]!)
+            if (task === undefined) throw new Error('Error: not_found: no such task')
+            const execution = task.executions.find(e => e.id === url.searchParams.get('execution'))
+            if (execution === undefined) throw new Error('Error: not_found: no such execution')
+            const commit = url.searchParams.get('commit')
+            const filePath = url.searchParams.get('path')
+            const ws = workspaces.get(task.workspaceId)
+            if (ws === undefined) throw new Error('Error: not_found: unknown workspace')
+            const cwd = execution.worktreePath ?? ws.path
+            let result = commit !== null
+              ? await options.git.showCommit(cwd, commit)
+              : filePath !== null ? await options.git.showPathDiff(cwd, filePath, execution.baseCommit) : undefined
+            // Fallback: the worktree may be gone — commits and committed
+            // ranges still resolve in the main repo.
+            if (result === undefined && execution.worktreePath !== undefined && cwd !== ws.path) {
+              result = commit !== null
+                ? await options.git.showCommit(ws.path, commit)
+                : filePath !== null && execution.baseCommit !== undefined
+                  ? await options.git.showPathDiff(ws.path, filePath, execution.baseCommit)
+                  : undefined
+            }
+            if (result === undefined) {
+              throw new Error('Error: invalid_input: 无法获取 diff（git 报错、对象不存在，或仅存于已删除的 worktree 且无基线）')
+            }
+            json(res, { ok: true, value: { diff: result.text, truncated: result.truncated } })
+          } catch (error) {
+            const f = toFail(error)
+            json(res, f.res, f.status)
+          }
+          return
+        }
+
+        // Templates listing (0.4.0).
+        if (pathname === `${ROUTE_PREFIX}/templates`) {
+          if (options.templates === undefined) {
+            const f = fail('invalid_input', 'template store unavailable')
+            json(res, f.res, 501)
+            return
+          }
+          json(res, { ok: true, value: { templates: await options.templates.list() } })
+          return
+        }
+
         const taskMatch = pathname.match(new RegExp(`^${ROUTE_PREFIX}/tasks/([^/]+)$`))
         if (taskMatch !== null) {
           const task = store.get(taskMatch[1]!)
@@ -194,6 +396,17 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
           const status = str(body, 'status') === null ? 'todo' as const : asStatus(str(body, 'status')!)
           const execution = normalizeExecution((body.execution as { mode?: string; cron?: string } | undefined) ?? {}, options.now())
           const model = body.model === undefined ? undefined : checkModel(body.model, options.modelProviders)
+          const isolationRaw = str(body, 'isolation')
+          const isolation = isolationRaw === null ? undefined : asIsolation(isolationRaw)
+          const presetId = normalizePresetId(str(body, 'presetId'))
+          let checklist: TaskRecord['checklist'] = undefined
+          if (body.checklist !== undefined) {
+            if (!Array.isArray(body.checklist) || body.checklist.some(c => typeof c !== 'string')) {
+              throw new Error('Error: invalid_input: checklist must be an array of strings')
+            }
+            const texts = (body.checklist as string[]).map(c => c.trim()).filter(c => c.length > 0)
+            if (texts.length > 0) checklist = checklistFromTexts(texts)
+          }
           const now = options.now()
           const task: TaskRecord = {
             id: newTaskId(),
@@ -206,6 +419,9 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
             blocked: false,
             execution,
             model,
+            ...(isolation !== undefined ? { isolation } : {}),
+            ...(presetId !== undefined ? { presetId } : {}),
+            ...(checklist !== undefined ? { checklist } : {}),
             version: 1,
             createdAt: now,
             updatedAt: now,
@@ -227,7 +443,9 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
       }
 
       // ------------------------------------------- POST /tasks/:id/{action}
-      const actionMatch = pathname.match(new RegExp(`^${ROUTE_PREFIX}/tasks/([^/]+)/(\\w+)$`))
+      // (\w+ after the id would not match hyphenated actions like
+      // worktree-remove, hence the explicit class.)
+      const actionMatch = pathname.match(new RegExp(`^${ROUTE_PREFIX}/tasks/([^/]+)/([\\w-]+)$`))
       if (actionMatch !== null) {
         const id = actionMatch[1]!
         const action = actionMatch[2]!
@@ -258,6 +476,25 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
             if (body.execution !== undefined) next.execution = normalizeExecution(body.execution as { mode?: string; cron?: string }, options.now())
             if (body.model === null) next.model = undefined
             else if (body.model !== undefined) next.model = checkModel(body.model, options.modelProviders)
+            // Isolation may change only before the first execution (分支与基线
+            // 取决于该选择 — plan §3.1: 执行开始后锁定).
+            const isolationRaw = str(body, 'isolation')
+            if (isolationRaw !== null) {
+              if (task.executions.length > 0 || task.status === 'in_progress') {
+                throw new Error('Error: invalid_input: isolation 已锁定（任务已有执行记录），不可修改')
+              }
+              next.isolation = asIsolation(isolationRaw)
+            }
+            // Preset may change any time: each run composes fresh.
+            if (body.presetId === null) delete next.presetId
+            else if (body.presetId !== undefined) next.presetId = normalizePresetId(str(body, 'presetId'))!
+            // Checklist (0.4.0): the GUI replaces the whole list; null clears.
+            if (body.checklist === null) delete next.checklist
+            else if (body.checklist !== undefined) {
+              const items = normalizeChecklist(body.checklist)
+              if (items.length > 0) next.checklist = items
+              else delete next.checklist
+            }
             next.version = task.version + 1
             next.updatedAt = options.now()
             next.updatedBy = { kind: 'user' }
@@ -336,6 +573,34 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
             const purge = body.purge === true
             if (purge) {
               if (task.trashedAt === undefined) throw new Error('Error: invalid_input: purge requires a trashed task (soft-delete first)')
+              // Worktree safety before purge (plan §3.3, 0.3.1): refuse while
+              // uncommitted work remains; otherwise clean the worktree and
+              // the task branch along with the ledger entry.
+              if (options.git !== undefined) {
+                const ws = workspaces.get(task.workspaceId)
+                if (ws !== undefined) {
+                  const path = worktreePathOf(ws.path, id)
+                  try {
+                    await options.git.removeWorktree(ws.path, path)
+                  } catch (error) {
+                    const message = error instanceof Error ? error.message : String(error)
+                    if (message.includes('未提交修改')) {
+                      throw new Error(`Error: invalid_input: ${message}；请先处理这些改动（提交、续跑或手动保存）再物理清除任务`)
+                    }
+                    if (/not a working tree|not a working-tree/i.test(message)) {
+                      // An unregistered leftover dir: plain fs removal.
+                      await rm(path, { recursive: true, force: true })
+                    } else {
+                      throw new Error(`Error: invalid_input: ${message}`)
+                    }
+                  }
+                  if (task.branch !== undefined) {
+                    try {
+                      await options.git.deleteBranch(ws.path, task.branch)
+                    } catch { /* best effort: the branch may outlive the task */ }
+                  }
+                }
+              }
               await store.mutate('task-deleted', ledger => {
                 ledger.tasks = ledger.tasks.filter(t => t.id !== id)
                 return []
@@ -363,7 +628,10 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
               json(res, f.res, 501)
               return
             }
-            const result = await options.run(id)
+            // `reuse: true` = 续跑: keep a live worktree/branch as-is instead
+            // of resetting to a fresh baseline (0.3.1).
+            const runOptions = body.reuse === true ? { reuseWorktree: true } : undefined
+            const result = await options.run(id, runOptions)
             if (result.ok) json(res, { ok: true, value: result }, 202)
             else {
               const f = fail('invalid_input', result.error)
@@ -385,6 +653,78 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
             }
             return
           }
+          if (action === 'merge') {
+            // ⇥ 合并 (detail page, user-only): merge the task branch into the
+            // main worktree with --no-ff; conflicts are reported verbatim.
+            if (options.git === undefined) {
+              const f = fail('invalid_input', 'git integration unavailable')
+              json(res, f.res, 501)
+              return
+            }
+            if (task.branch === undefined) throw new Error('Error: invalid_input: 该任务还没有 worktree 分支（未隔离执行过）')
+            if (task.status === 'in_progress') throw new Error('Error: invalid_input: 任务执行中，不能合并')
+            if (task.executions.some(e => e.outcome === 'running')) throw new Error('Error: invalid_input: 任务执行中，不能合并')
+            const ws = workspaces.get(task.workspaceId)
+            if (ws === undefined) throw new Error('Error: not_found: unknown workspace')
+            // No-op detection (0.3.1): a branch with no commits over HEAD
+            // merges as "already up to date" — report that instead of landing
+            // a bogus 已合并 comment.
+            let noop = false
+            try {
+              noop = await options.git.isAncestor(ws.path, task.branch)
+            } catch { /* fail-soft: proceed to the real merge */ }
+            if (noop) {
+              json(res, { ok: true, value: { merged: false, noop: true, branch: task.branch } })
+              return
+            }
+            try {
+              await options.git.merge(ws.path, task.branch)
+            } catch (error) {
+              throw new Error(`Error: invalid_input: ${error instanceof Error ? error.message : String(error)}`)
+            }
+            const mergedComment = { id: newCommentId(), body: normalizeBody(`[系统] 分支 ${task.branch} 已合并到主工作区（--no-ff）。`), version: 1, createdAt: options.now() }
+            const next = structuredClone(task)
+            next.comments.push(mergedComment)
+            next.version = task.version + 1
+            next.updatedAt = options.now()
+            await store.mutate('comment-added', ledger => {
+              const i = ledger.tasks.findIndex(t => t.id === id)
+              ledger.tasks[i] = next
+              return [next]
+            })
+            json(res, { ok: true, value: { merged: true, branch: task.branch } })
+            return
+          }
+          if (action === 'worktree-remove') {
+            // 🗑 删除 worktree (detail page): refuses uncommitted changes;
+            // optionally deletes the task branch after the worktree is gone.
+            if (options.git === undefined) {
+              const f = fail('invalid_input', 'git integration unavailable')
+              json(res, f.res, 501)
+              return
+            }
+            if (task.executions.some(e => e.outcome === 'running')) throw new Error('Error: invalid_input: 任务执行中，不能删除 worktree')
+            const ws = workspaces.get(task.workspaceId)
+            if (ws === undefined) throw new Error('Error: not_found: unknown workspace')
+            const path = worktreePathOf(ws.path, id)
+            try {
+              await options.git.removeWorktree(ws.path, path)
+            } catch (error) {
+              throw new Error(`Error: invalid_input: ${error instanceof Error ? error.message : String(error)}`)
+            }
+            let branchDeleted = false
+            let branchError: string | undefined
+            if (body.deleteBranch === true && task.branch !== undefined) {
+              try {
+                await options.git.deleteBranch(ws.path, task.branch)
+                branchDeleted = true
+              } catch (error) {
+                branchError = error instanceof Error ? error.message : String(error)
+              }
+            }
+            json(res, { ok: true, value: { removed: true, branchDeleted, ...(branchError !== undefined ? { branchError } : {}) } })
+            return
+          }
           const f = fail('not_found', `unknown action ${action}`)
           json(res, f.res, f.status)
         } catch (error) {
@@ -394,6 +734,144 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
         return
       }
 
+      // -------------------------------------- POST /worktree-cleanup (⚙ 诊断)
+      if (pathname === `${ROUTE_PREFIX}/worktree-cleanup`) {
+        try {
+          if (options.git === undefined) {
+            const f = fail('invalid_input', 'git integration unavailable')
+            json(res, f.res, 501)
+            return
+          }
+          const workspaceId = str(body, 'workspaceId') ?? ''
+          const taskId = str(body, 'taskId') ?? ''
+          const ws = workspaces.get(workspaceId)
+          if (ws === undefined) throw new Error('Error: not_found: unknown workspace')
+          // Only dirs owned by NO ledger task may be cleaned here; live tasks
+          // remove their worktree from the detail page.
+          if (store.get(taskId) !== undefined) throw new Error('Error: invalid_input: 任务仍在看板中，请从任务详情页删除其 worktree')
+          const path = worktreePathOf(ws.path, taskId)
+          try {
+            await options.git.removeWorktree(ws.path, path)
+          } catch (error) {
+            const message = error instanceof Error ? error.message : String(error)
+            // An unregistered leftover (git no longer knows this worktree):
+            // fall back to direct fs removal — the dir lives inside the
+            // plugin's own .dsh-worktrees scope.
+            if (/not a working tree|not a working-tree/i.test(message)) {
+              await rm(path, { recursive: true, force: true })
+            } else {
+              throw new Error(`Error: invalid_input: ${message}`)
+            }
+          }
+          json(res, { ok: true, value: { cleaned: true, path } })
+        } catch (error) {
+          const f = toFail(error)
+          json(res, f.res, f.status)
+        }
+        return
+      }
+
+      // ---------------------------------------------- POST /import/preview
+      // (0.4.0) Dry-run: classify every task in the uploaded ledger file
+      // against the live one; nothing is written.
+      if (pathname === `${ROUTE_PREFIX}/import/preview`) {
+        try {
+          const known = new Set(store.snapshot().tasks.map(t => t.id))
+          const plan = validateLedgerImport(body, known, options.now())
+          json(res, {
+            ok: true,
+            value: {
+              plan: {
+                create: plan.create.map(t => ({ id: t.id, title: t.title, status: t.status })),
+                overwrite: plan.overwrite.map(t => ({ id: t.id, title: t.title, status: t.status })),
+                invalid: plan.invalid,
+              },
+            },
+          })
+        } catch (error) {
+          const f = toFail(error)
+          json(res, f.res, f.status)
+        }
+        return
+      }
+
+      // ------------------------------------------------------ POST /import
+      // (0.4.0) Commit an import. mode=merge upserts (create + overwrite by
+      // id); mode=replace swaps the WHOLE ledger (invalid entries dropped)
+      // after writing a timestamped backup of the current one.
+      if (pathname === `${ROUTE_PREFIX}/import`) {
+        try {
+          const mode = str(body, 'mode') === 'replace' ? 'replace' as const : 'merge' as const
+          const raw = body.ledger
+          const known = new Set(store.snapshot().tasks.map(t => t.id))
+          const plan = validateLedgerImport(raw, known, options.now())
+          const imported = [...plan.create, ...plan.overwrite]
+          if (mode === 'replace' && imported.length === 0) {
+            throw new Error('Error: invalid_input: 导入文件没有可导入的任务，已拒绝整册替换')
+          }
+          let backupFile: string | undefined
+          if (mode === 'replace' && store.snapshot().tasks.length > 0) {
+            backupFile = await store.backup()
+          }
+          let replacedTotal: number | undefined
+          await store.mutate('task-created', ledger => {
+            if (mode === 'replace') {
+              replacedTotal = ledger.tasks.length
+              ledger.tasks = structuredClone(imported)
+              return ledger.tasks
+            }
+            const byId = new Map(ledger.tasks.map(t => [t.id, t]))
+            for (const task of imported) byId.set(task.id, structuredClone(task))
+            ledger.tasks = [...byId.values()]
+            return structuredClone(imported)
+          })
+          json(res, {
+            ok: true,
+            value: {
+              mode,
+              created: plan.create.length,
+              overwritten: plan.overwrite.length,
+              ...(mode === 'replace' ? { replacedTotal } : {}),
+              ...(backupFile !== undefined ? { backupFile } : {}),
+            },
+          })
+        } catch (error) {
+          const f = toFail(error)
+          json(res, f.res, f.status)
+        }
+        return
+      }
+
+      // ------------------------------------------- POST /templates (+delete)
+      if (pathname === `${ROUTE_PREFIX}/templates` || pathname === `${ROUTE_PREFIX}/templates/delete`) {
+        try {
+          if (options.templates === undefined) {
+            const f = fail('invalid_input', 'template store unavailable')
+            json(res, f.res, 501)
+            return
+          }
+          if (pathname.endsWith('/delete')) {
+            const id = str(body, 'id') ?? ''
+            if (id.length === 0) throw new Error('Error: invalid_input: id required')
+            const deleted = await options.templates.remove(id)
+            json(res, { ok: true, value: { deleted } })
+            return
+          }
+          const name = str(body, 'name') ?? ''
+          if (name.trim().length === 0) throw new Error('Error: invalid_input: name required')
+          const template = await options.templates.upsert({
+            id: str(body, 'id') ?? undefined,
+            name,
+            task: normalizeTemplateSpec(body.task),
+          })
+          json(res, { ok: true, value: template }, 201)
+        } catch (error) {
+          const f = toFail(error)
+          json(res, f.res, f.status)
+        }
+        return
+      }
+
       res.writeHead(404)
       res.end()
     } catch (error) {

package/src/host/store.ts

@@ -103,6 +103,19 @@ export class TaskStore {
     return () => this.subscribers.delete(fn)
   }
 
+  /**
+   * Write a timestamped backup copy of the current ledger next to the live
+   * file (import-replace safety, 0.4.0). Never throws the caller's flow —
+   * a backup failure fails the import itself.
+   * @returns the backup file path.
+   */
+  async backup(): Promise<string> {
+    await this.load()
+    const target = `${this.file}.backup-${Date.now()}`
+    await persistAtomic(target, JSON.stringify(this.ledger, null, 2))
+    return target
+  }
+
   /**
    * Run one mutation inside the serial queue. The mutator works on a
    * structured clone; returning `undefined` aborts with no write.