dsh-taskboard 0.3.3 → 0.4.1

package/src/shared/protocol.ts

@@ -263,6 +263,38 @@ export type CommentRecord = {
 /** One commit produced by an isolated execution (hash + subject). */
 export type CommitInfo = { hash: string; subject: string }
 
+/**
+ * The structured execution report an agent submits at handoff (0.4.0).
+ * Commits/dirty/diff facts are host-collected git evidence — the report
+ * covers the BUSINESS side the host cannot see.
+ */
+export type ExecutionReport = {
+  /** What was done (1..2000 chars, required). */
+  summary: string
+  /** Files the agent changed (paths, ≤50 × 300 chars). */
+  changedFiles: string[]
+  /** How the work was self-verified (≤50 × 300 chars). */
+  checks: string[]
+  /** Produced artifacts worth reviewing (≤30 × 300 chars). */
+  artifacts: string[]
+  /** Known remaining risks / follow-ups (≤2000 chars, '' allowed). */
+  risk: string
+}
+
+/** One Definition-of-Done checklist item (0.4.0). */
+export type ChecklistItem = {
+  id: string
+  /** What must be true for acceptance (1..200 chars). */
+  text: string
+  checked: boolean
+  /** Who checked it: an agent session id, or 'user' for GUI toggles. */
+  checkedBy?: string
+  /** When it was checked (epoch ms). */
+  checkedAt?: number
+  /** Evidence note attached when checking (≤400 chars). */
+  note?: string
+}
+
 /** One execution attempt of a task. */
 export type ExecutionRecord = {
   id: string
@@ -298,6 +330,8 @@ export type ExecutionRecord = {
   diffStat?: string
   /** How many files differ between baseCommit and headCommit. */
   changedFiles?: number
+  /** The agent's structured report, submitted via taskboard_execution_report. */
+  report?: ExecutionReport
 }
 
 /** The per-model override a task may carry; absent = session default model. */
@@ -330,6 +364,12 @@ export type TaskRecord = {
    * tool set. Editable any time (each run composes fresh).
    */
   presetId?: string
+  /**
+   * Definition-of-Done acceptance checklist (0.4.0). Agents may append items
+   * and check/uncheck them (with evidence); the GUI may edit the whole list.
+   * Unchecked items highlight at review time; done stays user-only.
+   */
+  checklist?: ChecklistItem[]
   /**
    * The task branch fixed at the FIRST worktree creation (`task/<标题>+<taskId>`).
    * Renaming the task afterwards never changes it (history preservation).
@@ -408,6 +448,11 @@ export function newCommentId(): string {
   return `c-${Date.now().toString(36)}-${suffix()}`
 }
 
+/** Mint a checklist item id. */
+export function newChecklistItemId(): string {
+  return `k-${Date.now().toString(36)}-${suffix()}`
+}
+
 /** Mint an execution id. */
 export function newExecutionId(): string {
   return `e-${Date.now().toString(36)}-${suffix()}`
@@ -562,6 +607,301 @@ export function normalizeModel(raw: unknown): TaskModel {
   return { provider: p, model: m }
 }
 
+// ---------------------------------------------------------------------------
+// checklist + report validation (0.4.0)
+// ---------------------------------------------------------------------------
+
+/** Checklist size cap per task. */
+export const MAX_CHECKLIST_ITEMS = 30
+
+/** Checklist item text cap (chars). */
+export const MAX_CHECKLIST_TEXT = 200
+
+/**
+ * Validate and normalize one checklist text line: trimmed, 1..200 chars.
+ * @param raw - the raw text.
+ * @throws when empty or too long.
+ */
+export function normalizeChecklistText(raw: string): string {
+  const t = raw.trim()
+  if (t.length === 0 || t.length > MAX_CHECKLIST_TEXT) {
+    throw new Error(`checklist item text must be 1..${MAX_CHECKLIST_TEXT} characters`)
+  }
+  return t
+}
+
+/**
+ * Build a fresh unchecked checklist from plain text lines (create route /
+ * templates / tool adds).
+ * @param texts - the item texts (validated individually).
+ */
+export function checklistFromTexts(texts: readonly string[]): ChecklistItem[] {
+  const items = texts.map(text => ({ id: newChecklistItemId(), text: normalizeChecklistText(text), checked: false }))
+  if (items.length > MAX_CHECKLIST_ITEMS) {
+    throw new Error(`checklist may hold at most ${MAX_CHECKLIST_ITEMS} items`)
+  }
+  return items
+}
+
+/**
+ * Validate and normalize a full checklist array (GUI update route, import):
+ * missing ids are minted, text is checked, checked flags must be booleans,
+ * checkedBy/checkedAt are kept only on checked items.
+ * @param raw - untyped array from the wire.
+ * @throws with a readable reason on any invalid entry.
+ */
+export function normalizeChecklist(raw: unknown): ChecklistItem[] {
+  if (!Array.isArray(raw)) throw new Error('checklist must be an array')
+  if (raw.length > MAX_CHECKLIST_ITEMS) {
+    throw new Error(`checklist may hold at most ${MAX_CHECKLIST_ITEMS} items`)
+  }
+  return raw.map((entry): ChecklistItem => {
+    if (typeof entry !== 'object' || entry === null) throw new Error('checklist item must be an object')
+    const e = entry as Record<string, unknown>
+    const text = normalizeChecklistText(typeof e.text === 'string' ? e.text : '')
+    const id = typeof e.id === 'string' && e.id.trim().length > 0 ? e.id.trim() : newChecklistItemId()
+    const checked = e.checked === true
+    const checkedBy = typeof e.checkedBy === 'string' ? e.checkedBy.trim().slice(0, 100) : undefined
+    const checkedAt = typeof e.checkedAt === 'number' && Number.isFinite(e.checkedAt) ? e.checkedAt : undefined
+    const note = typeof e.note === 'string' && e.note.trim().length > 0 ? e.note.trim().slice(0, 400) : undefined
+    if (!checked) return { id, text, checked: false }
+    return {
+      id,
+      text,
+      checked: true,
+      ...(checkedBy !== undefined && checkedBy.length > 0 ? { checkedBy } : {}),
+      ...(checkedAt !== undefined ? { checkedAt } : {}),
+      ...(note !== undefined ? { note } : {}),
+    }
+  })
+}
+
+/** Checklist progress: how many items are checked (absent checklist → 0/0). */
+export function checklistProgress(task: Pick<TaskRecord, 'checklist'>): { done: number; total: number } {
+  const items = task.checklist ?? []
+  return { done: items.filter(i => i.checked).length, total: items.length }
+}
+
+/** Report string-list caps. */
+const REPORT_LIST_CAPS = { changedFiles: 50, checks: 50, artifacts: 30 } as const
+
+/** Per-entry cap for report lists (chars). */
+const REPORT_ENTRY_MAX = 300
+
+/** Validate one report string list: strings trimmed 1..300 chars. */
+function normalizeReportList(raw: unknown, field: keyof typeof REPORT_LIST_CAPS): string[] {
+  if (raw === undefined) return []
+  if (!Array.isArray(raw)) throw new Error(`report.${field} must be an array of strings`)
+  const out = raw.map(entry => {
+    if (typeof entry !== 'string') throw new Error(`report.${field} must be an array of strings`)
+    const t = entry.trim()
+    if (t.length === 0 || t.length > REPORT_ENTRY_MAX) {
+      throw new Error(`report.${field} entries must be 1..${REPORT_ENTRY_MAX} characters`)
+    }
+    return t
+  })
+  if (out.length > REPORT_LIST_CAPS[field]) {
+    throw new Error(`report.${field} may hold at most ${REPORT_LIST_CAPS[field]} entries`)
+  }
+  return out
+}
+
+/**
+ * Validate and normalize a structured execution report.
+ * @param raw - untyped tool/route input.
+ * @throws with a readable reason on any invalid field.
+ */
+export function normalizeExecutionReport(raw: unknown): ExecutionReport {
+  if (typeof raw !== 'object' || raw === null) throw new Error('report must be an object')
+  const e = raw as Record<string, unknown>
+  const summary = typeof e.summary === 'string' ? e.summary.trim() : ''
+  if (summary.length === 0 || summary.length > 2000) {
+    throw new Error('report.summary must be 1..2000 characters')
+  }
+  const risk = typeof e.risk === 'string' ? e.risk.trim().slice(0, 2000) : ''
+  return {
+    summary,
+    changedFiles: normalizeReportList(e.changedFiles, 'changedFiles'),
+    checks: normalizeReportList(e.checks, 'checks'),
+    artifacts: normalizeReportList(e.artifacts, 'artifacts'),
+    risk,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ledger import validation (0.4.0)
+// ---------------------------------------------------------------------------
+
+/** Result classifying every task in an import file against the live ledger. */
+export type ImportPlan = {
+  /** Structurally valid tasks whose ids are new (merge adds them). */
+  create: TaskRecord[]
+  /** Structurally valid tasks whose ids already exist (merge replaces them). */
+  overwrite: TaskRecord[]
+  /** Invalid entries with a human-readable reason (never imported). */
+  invalid: Array<{ id?: string; reason: string }>
+}
+
+/** One unknown-value read helper: string fields with defaults. */
+function strOr(raw: Record<string, unknown>, key: string, fallback: string): string {
+  const v = raw[key]
+  return typeof v === 'string' ? v : fallback
+}
+
+/** One unknown-value read helper: finite numbers with defaults. */
+function numOr(raw: Record<string, unknown>, key: string, fallback: number): number {
+  const v = raw[key]
+  return typeof v === 'number' && Number.isFinite(v) ? v : fallback
+}
+
+/**
+ * Validate ONE imported task record (pure): rebuilds it field by field with
+ * the normal validators, minting missing ids and re-arming cron. Executions
+ * left `running` by the exporting machine are marked failed — their
+ * settlement watchers died there and can never settle here.
+ * @param raw - the untyped record.
+ * @param now - current epoch ms (defaults for timestamps).
+ * @returns the rebuilt record, or a rejection reason.
+ */
+export function validateImportedTask(raw: unknown, now: number): { ok: true; task: TaskRecord } | { ok: false; reason: string } {
+  if (typeof raw !== 'object' || raw === null) return { ok: false, reason: 'not an object' }
+  const e = raw as Record<string, unknown>
+  const id = typeof e.id === 'string' ? e.id.trim() : ''
+  const fail = (reason: string): { ok: false; reason: string } => ({ ok: false, reason })
+  if (id.length === 0 || id.length > 100) return fail('missing/invalid id')
+  try {
+    const execution = normalizeExecution(
+      typeof e.execution === 'object' && e.execution !== null ? e.execution as { mode?: string; cron?: string } : {},
+      now,
+    )
+    const comments: CommentRecord[] = []
+    if (Array.isArray(e.comments)) {
+      for (const c of e.comments) {
+        if (typeof c !== 'object' || c === null) return fail('invalid comment entry')
+        const ce = c as Record<string, unknown>
+        const body = typeof ce.body === 'string' ? ce.body : ''
+        if (body.trim().length === 0 || body.length > 4000) return fail('invalid comment body')
+        comments.push({
+          id: typeof ce.id === 'string' && ce.id.length > 0 ? ce.id : newCommentId(),
+          body,
+          version: numOr(ce, 'version', 1),
+          createdAt: numOr(ce, 'createdAt', now),
+          ...(typeof ce.threadId === 'string' ? { threadId: ce.threadId } : {}),
+        })
+      }
+    } else return fail('comments must be an array')
+    const executions: ExecutionRecord[] = []
+    if (Array.isArray(e.executions)) {
+      for (const x of e.executions) {
+        if (typeof x !== 'object' || x === null) return fail('invalid execution entry')
+        const xe = x as Record<string, unknown>
+        const trigger = xe.trigger === 'scheduled' ? 'scheduled' : 'manual'
+        const outcomeRaw = xe.outcome
+        if (outcomeRaw !== 'running' && outcomeRaw !== 'succeeded' && outcomeRaw !== 'failed' && outcomeRaw !== 'cancelled') {
+          return fail('invalid execution outcome')
+        }
+        // A running execution from the exporting machine can never settle
+        // here — import it as failed with the reason recorded.
+        const outcome = outcomeRaw === 'running' ? 'failed' as const : outcomeRaw
+        executions.push({
+          id: typeof xe.id === 'string' && xe.id.length > 0 ? xe.id : newExecutionId(),
+          ...(typeof xe.sessionId === 'string' ? { sessionId: xe.sessionId } : {}),
+          trigger,
+          ...(typeof xe.startedAt === 'number' ? { startedAt: xe.startedAt } : {}),
+          ...(typeof xe.endedAt === 'number' ? { endedAt: xe.endedAt } : {}),
+          outcome,
+          ...(outcomeRaw === 'running' ? { error: 'imported while still running (settlement watcher died with the exporting host)' } : (typeof xe.error === 'string' ? { error: xe.error } : {})),
+          ...(typeof xe.isolation === 'string' && (xe.isolation === 'worktree' || xe.isolation === 'none') ? { isolation: xe.isolation } : {}),
+          ...(typeof xe.isolationNote === 'string' ? { isolationNote: xe.isolationNote } : {}),
+          ...(typeof xe.branch === 'string' ? { branch: xe.branch } : {}),
+          ...(typeof xe.worktreePath === 'string' ? { worktreePath: xe.worktreePath } : {}),
+          ...(typeof xe.baseCommit === 'string' ? { baseCommit: xe.baseCommit } : {}),
+          ...(typeof xe.headCommit === 'string' ? { headCommit: xe.headCommit } : {}),
+          ...(Array.isArray(xe.commits) ? { commits: xe.commits.filter((c): c is CommitInfo =>
+            typeof c === 'object' && c !== null && typeof (c as CommitInfo).hash === 'string' && typeof (c as CommitInfo).subject === 'string') } : {}),
+          ...(typeof xe.commitsTotal === 'number' ? { commitsTotal: xe.commitsTotal } : {}),
+          ...(Array.isArray(xe.dirtyFiles) ? { dirtyFiles: xe.dirtyFiles.filter((l): l is string => typeof l === 'string') } : {}),
+          ...(typeof xe.dirtyFilesTotal === 'number' ? { dirtyFilesTotal: xe.dirtyFilesTotal } : {}),
+          ...(typeof xe.diffStat === 'string' ? { diffStat: xe.diffStat } : {}),
+          ...(typeof xe.changedFiles === 'number' ? { changedFiles: xe.changedFiles } : {}),
+          ...(typeof xe.report === 'object' && xe.report !== null ? { report: normalizeExecutionReport(xe.report) } : {}),
+        })
+      }
+    } else return fail('executions must be an array')
+    const status = asStatus(strOr(e, 'status', 'todo'))
+    const actorOf = (v: unknown): Actor => (typeof v === 'object' && v !== null && (v as Actor).kind === 'agent' && typeof (v as { sessionId?: unknown }).sessionId === 'string'
+      ? { kind: 'agent', sessionId: (v as { sessionId: string }).sessionId }
+      : { kind: 'user' })
+    const task: TaskRecord = {
+      id,
+      title: normalizeTitle(strOr(e, 'title', '')),
+      description: strOr(e, 'description', '').trim(),
+      prompt: normalizePrompt(strOr(e, 'prompt', '')),
+      workspaceId: strOr(e, 'workspaceId', ''),
+      urgency: asUrgency(strOr(e, 'urgency', 'normal')),
+      status,
+      blocked: e.blocked === true,
+      execution,
+      ...(typeof e.model === 'object' && e.model !== null ? { model: normalizeModel(e.model) } : {}),
+      ...(typeof e.isolation === 'string' && (e.isolation === 'worktree' || e.isolation === 'none') ? { isolation: e.isolation } : {}),
+      ...(typeof e.presetId === 'string' && e.presetId.trim().length > 0 ? { presetId: e.presetId.trim() } : {}),
+      ...(Array.isArray(e.checklist) ? { checklist: normalizeChecklist(e.checklist) } : {}),
+      ...(typeof e.branch === 'string' ? { branch: e.branch } : {}),
+      ...(status === 'in_progress' && typeof e.claimedBy === 'string' ? { claimedBy: e.claimedBy } : {}),
+      ...(status === 'in_progress' && typeof e.claimedAt === 'number' ? { claimedAt: e.claimedAt } : {}),
+      version: Math.max(1, Math.trunc(numOr(e, 'version', 1))),
+      createdAt: numOr(e, 'createdAt', now),
+      updatedAt: numOr(e, 'updatedAt', now),
+      createdBy: actorOf(e.createdBy),
+      updatedBy: actorOf(e.updatedBy),
+      comments,
+      executions,
+      ...(typeof e.executionsPruned === 'number' ? { executionsPruned: e.executionsPruned } : {}),
+      ...(typeof e.trashedAt === 'number' ? { trashedAt: e.trashedAt } : {}),
+    }
+    if (task.workspaceId.length === 0) return fail('missing workspaceId')
+    return { ok: true, task }
+  } catch (error) {
+    return fail(error instanceof Error ? error.message : String(error))
+  }
+}
+
+/**
+ * Validate a whole imported ledger and classify its tasks against the live
+ * one (pure). Duplicate ids INSIDE the file are invalid (first wins, later
+ * copies reported); schemaVersion must match {@link LEDGER_SCHEMA_VERSION}.
+ * @param raw - the parsed import file.
+ * @param knownIds - live ledger task ids.
+ * @param now - current epoch ms.
+ * @throws when the file is not a ledger or the schemaVersion is unsupported.
+ */
+export function validateLedgerImport(raw: unknown, knownIds: ReadonlySet<string>, now: number): ImportPlan {
+  if (typeof raw !== 'object' || raw === null) throw new Error('导入文件不是 JSON 对象')
+  const e = raw as Record<string, unknown>
+  if (e.schemaVersion !== LEDGER_SCHEMA_VERSION) {
+    throw new Error(`不支持的 schemaVersion ${String(e.schemaVersion)}（当前支持 ${LEDGER_SCHEMA_VERSION}）`)
+  }
+  if (!Array.isArray(e.tasks)) throw new Error('导入文件的 tasks 不是数组')
+  const plan: ImportPlan = { create: [], overwrite: [], invalid: [] }
+  const seen = new Set<string>()
+  for (const entry of e.tasks) {
+    const id = typeof (entry as { id?: unknown })?.id === 'string' ? (entry as { id: string }).id : undefined
+    const result = validateImportedTask(entry, now)
+    if (!result.ok) {
+      plan.invalid.push({ ...(id !== undefined ? { id } : {}), reason: result.reason })
+      continue
+    }
+    if (seen.has(result.task.id)) {
+      plan.invalid.push({ id: result.task.id, reason: '文件内重复 id' })
+      continue
+    }
+    seen.add(result.task.id)
+    if (knownIds.has(result.task.id)) plan.overwrite.push(result.task)
+    else plan.create.push(result.task)
+  }
+  return plan
+}
+
 /**
  * Compact list-projection of a task (token-friendly for `taskboard_list`).
  * @param task - the task.
@@ -580,6 +920,8 @@ export type TaskSummary = {
   claimOwner?: string
   commentCount: number
   lastExecutionOutcome?: ExecutionRecord['outcome']
+  /** Checklist progress (present only when the task has a checklist). */
+  checklist?: { done: number; total: number }
   trashed: boolean
 }
 
@@ -589,6 +931,7 @@ export type TaskSummary = {
  */
 export function summarize(task: TaskRecord): TaskSummary {
   const last = task.executions.length > 0 ? task.executions[task.executions.length - 1] : undefined
+  const checklist = task.checklist !== undefined && task.checklist.length > 0 ? checklistProgress(task) : undefined
   return {
     id: task.id,
     title: task.title,
@@ -603,6 +946,7 @@ export function summarize(task: TaskRecord): TaskSummary {
     claimOwner: isClaimedBy(task),
     commentCount: task.comments.length,
     lastExecutionOutcome: last?.outcome,
+    ...(checklist !== undefined ? { checklist } : {}),
     trashed: task.trashedAt !== undefined,
   }
 }

package/src/shared/version.ts

@@ -6,4 +6,4 @@
  */
 
 /** The package version (must equal package.json "version"). */
-export const PLUGIN_VERSION = '0.3.3'
+export const PLUGIN_VERSION = '0.4.1'