@fonlan/dsh-task-kanban 0.1.0

package/src/server/settings.ts

@@ -0,0 +1,69 @@
+/**
+ * User-facing plugin settings (global parallel worker count, default model),
+ * persisted through the settings service namespace `task-kanban`. The DSH
+ * settings service requires a lowercase kebab-case namespace
+ * (/^[a-z][a-z0-9-]*$/), so the scoped package name cannot be used here.
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { settingsNamespace } from '@deepseek-ai/dsh-settings'
+import type { KanbanSettingsShape } from '../shared/card.js'
+
+export const KANBAN_SETTINGS_NS = settingsNamespace('task-kanban')
+
+export const KanbanSettingsSchema = z.object({
+  maxParallelWorkers: z.natural().min(1).default(1),
+  defaultModel: z.string().default(''),
+})
+
+export interface KanbanSettingsFace {
+  get(): KanbanSettingsShape
+  update(patch: Partial<KanbanSettingsShape>): Promise<void>
+  /** Default provider/model route from the agent-default-model settings namespace. */
+  defaultModelRoute(): { provider?: string; model?: string }
+}
+
+/** Structural settings-service subset; the real service resolves the schema. */
+interface SettingsServiceLike {
+  register(ns: unknown, schema: unknown): unknown
+  update(ns: unknown, patch: Record<string, unknown>, expectedRevision?: number): Promise<unknown>
+}
+
+export function registerSettings(ctx: Context): KanbanSettingsFace {
+  let current: KanbanSettingsShape = { maxParallelWorkers: 1, defaultModel: '' }
+  let service: SettingsServiceLike | undefined
+  ctx.inject(['settings'], (sctx) => {
+    service = sctx.settings as unknown as SettingsServiceLike
+    const scope = service.register(KANBAN_SETTINGS_NS, KanbanSettingsSchema) as {
+      get(): KanbanSettingsShape
+      watch(callback: (next: KanbanSettingsShape) => void): () => void
+    }
+    current = scope.get()
+    scope.watch((next) => { current = next })
+  })
+  return {
+    get: () => current,
+    defaultModelRoute: () => {
+      if (service === undefined) return {}
+      try {
+        const descriptors = (service as unknown as { describe(opts: { redactSecrets: boolean }): Array<{ ns: unknown; value: unknown }> })
+          .describe({ redactSecrets: true })
+        for (const d of descriptors) {
+          if (String(d.ns) === 'agent-default-model') {
+            const v = (d.value ?? {}) as { provider?: string; model?: string }
+            return { provider: v.provider, model: v.model }
+          }
+        }
+      } catch {
+        // fall through
+      }
+      return {}
+    },
+    update: async (patch) => {
+      if (service === undefined) {
+        throw new Error('@fonlan/dsh-task-kanban: settings service is not available in this profile')
+      }
+      await service.update(KANBAN_SETTINGS_NS, patch as Record<string, unknown>)
+    },
+  }
+}

package/src/server/task-store.ts

@@ -0,0 +1,128 @@
+import { randomUUID } from 'node:crypto'
+import { mkdir, readFile, writeFile, rename, readdir, rm } from 'node:fs/promises'
+import { join } from 'node:path'
+import { CARD_SCHEMA_VERSION, type KanbanCard } from '../shared/card.js'
+
+const TASKS_REL = ['.dsh', 'task-kanban', 'tasks']
+
+/**
+ * File-backed task store: one JSON file per card under
+ * `<workspace>/.dsh/task-kanban/tasks/<id>.json`. In-process cache plus
+ * atomic (tmp+rename) writes, with a per-card mutex so worker and RPC
+ * mutations never interleave.
+ */
+export class TaskStore {
+  private cache = new Map<string, KanbanCard>()
+  private locks = new Map<string, Promise<unknown>>()
+
+  private taskDir(workspacePath: string): string {
+    return join(workspacePath, ...TASKS_REL)
+  }
+
+  private fileOf(workspacePath: string, id: string): string {
+    return join(this.taskDir(workspacePath), `${id}.json`)
+  }
+
+  private withLock<T>(key: string, fn: () => Promise<T>): Promise<T> {
+    const prev = this.locks.get(key) ?? Promise.resolve()
+    const next = prev.then(fn, fn)
+    this.locks.set(key, next.catch(() => undefined))
+    return next
+  }
+
+  async list(workspacePath: string): Promise<KanbanCard[]> {
+    const dir = this.taskDir(workspacePath)
+    let files: string[]
+    try {
+      files = await readdir(dir)
+    } catch {
+      return []
+    }
+    const out: KanbanCard[] = []
+    for (const f of files) {
+      if (!f.endsWith('.json')) continue
+      const id = f.slice(0, -5)
+      const card = await this.get(workspacePath, id)
+      if (card !== undefined) out.push(card)
+    }
+    out.sort((a, b) => a.createdAt - b.createdAt)
+    return out
+  }
+
+  async get(workspacePath: string, id: string): Promise<KanbanCard | undefined> {
+    const cached = this.cache.get(id)
+    if (cached !== undefined && cached.workspacePath === workspacePath) return cached
+    try {
+      const raw = await readFile(this.fileOf(workspacePath, id), 'utf8')
+      const card = JSON.parse(raw) as KanbanCard
+      this.cache.set(id, card)
+      return card
+    } catch {
+      return undefined
+    }
+  }
+
+  async create(input: {
+    workspacePath: string
+    requirement: string
+    model: string
+    provider?: string
+    status?: KanbanCard['status']
+  }): Promise<KanbanCard> {
+    const id = randomUUID()
+    const card: KanbanCard = {
+      schemaVersion: CARD_SCHEMA_VERSION,
+      id,
+      workspacePath: input.workspacePath,
+      requirement: input.requirement,
+      model: input.model,
+      ...(input.provider !== undefined ? { provider: input.provider } : {}),
+      status: input.status ?? 'draft',
+      currentPhase: 0,
+      phaseCount: 0,
+      sessions: { refinement: [], phases: [], merge: [] },
+      createdAt: Date.now(),
+    }
+    await this.write(card)
+    return card
+  }
+
+  /** Run a mutation under the card's lock; returns the updated card. */
+  async mutate(
+    id: string,
+    fn: (card: KanbanCard) => void | Promise<void>,
+    workspacePath?: string,
+  ): Promise<KanbanCard | undefined> {
+    return this.withLock(id, async () => {
+      let card = this.cache.get(id)
+      if ((card === undefined || (workspacePath !== undefined && card.workspacePath !== workspacePath)) && workspacePath !== undefined) {
+        card = await this.get(workspacePath, id)
+      }
+      if (card === undefined) return undefined
+      await fn(card)
+      await this.write(card)
+      return card
+    })
+  }
+
+  private async write(card: KanbanCard): Promise<void> {
+    const dir = this.taskDir(card.workspacePath)
+    await mkdir(dir, { recursive: true })
+    const file = this.fileOf(card.workspacePath, card.id)
+    const tmp = file + '.tmp'
+    await writeFile(tmp, JSON.stringify(card, null, 2), 'utf8')
+    await rename(tmp, file)
+    this.cache.set(card.id, card)
+  }
+
+  async remove(workspacePath: string, id: string): Promise<void> {
+    await this.withLock(id, async () => {
+      this.cache.delete(id)
+      try {
+        await rm(this.fileOf(workspacePath, id), { force: true })
+      } catch {
+        // already gone
+      }
+    })
+  }
+}

package/src/server/tools.ts

@@ -0,0 +1,131 @@
+/**
+ * The three kanban model-facing tools, registered SCOPED into the sessions
+ * that need them (only refinement/phase/merge agents see them):
+ *  - kanban_write_plan      → refinement session writes the plan back to the card
+ *  - kanban_phase_complete  → a phase implementation session declares its phase done
+ *  - kanban_merge_resolved  → a conflict merge session declares conflicts resolved
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { Context } from '@deepseek-ai/cordis'
+import { validatePlan } from '../shared/plan.js'
+import type { Plan } from '../shared/card.js'
+
+export interface KanbanToolResolver {
+  /** Resolve the card id attached to a calling session id. */
+  cardOfSession(sessionId?: string): string | undefined
+  writePlan(cardId: string, plan: Plan): Promise<void>
+  /** Mark the phase done; returns the phase id for the tool output. */
+  phaseComplete(sessionId: string, summary: string): Promise<string>
+  mergeResolved(sessionId: string): Promise<void>
+}
+
+export function registerKanbanTools(agentCtx: Context, resolver: KanbanToolResolver): void {
+  agentCtx.tools.register(defineTool({
+    name: 'kanban_write_plan',
+    description: '把当前需求的完整分阶段实现计划写回任务卡片。调用一次，参数为完整计划（title、summary、按执行顺序排列的 phases）。成功写回后本细化会话即结束。',
+    parameters: {
+      title: { type: 'string', required: true, description: '计划标题' },
+      summary: { type: 'string', required: true, description: '计划摘要' },
+      phases: {
+        type: 'array',
+        required: true,
+        items: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            id: { type: 'string', required: true, description: '阶段 id，如 p1' },
+            title: { type: 'string', required: true, description: '阶段标题' },
+            goal: { type: 'string', required: true, description: '阶段目标：本阶段要交付什么' },
+          },
+        },
+        description: '按顺序串行执行的实现阶段；必须非空',
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean', required: true },
+          taskId: { type: 'string', required: true },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: `实现计划已写回任务卡片 ${value.taskId}。` }],
+    },
+    async execute(args, exec) {
+      const sessionId = exec.agent?.id
+      const cardId = resolver.cardOfSession(sessionId)
+      if (cardId === undefined) {
+        throw new Error('当前会话没有关联的任务卡片，无法写回计划')
+      }
+      const result = validatePlan(args)
+      if (!result.ok) {
+        throw new Error(result.message)
+      }
+      const plan = result.plan
+      await resolver.writePlan(cardId, plan)
+      exec.concludeTurn()
+      return { ok: true, taskId: cardId }
+    },
+  }))
+
+  agentCtx.tools.register(defineTool({
+    name: 'kanban_phase_complete',
+    description: '声明当前 phase 实现完成。在工作完成后必须显式调用本工具（附完成摘要），否则该 phase 会被视为未完成。',
+    parameters: {
+      summary: { type: 'string', required: true, description: '本 phase 完成了什么的简要说明' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean', required: true },
+          phase: { type: 'string', required: true },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: `phase ${value.phase} 已标记完成。` }],
+    },
+    async execute(args, exec) {
+      const sessionId = exec.agent?.id
+      const cardId = resolver.cardOfSession(sessionId)
+      if (cardId === undefined) {
+        throw new Error('当前会话没有关联的任务卡片')
+      }
+      if (typeof args.summary !== 'string' || args.summary.trim() === '') {
+        throw new Error('summary 不能为空')
+      }
+      const phase = await resolver.phaseComplete(sessionId!, args.summary)
+      exec.concludeTurn()
+      return { ok: true, phase }
+    },
+  }))
+
+  agentCtx.tools.register(defineTool({
+    name: 'kanban_merge_resolved',
+    description: '声明当前目录中的合并冲突已全部解决。只用于合并冲突解决会话；声明后本会话即将结束。',
+    parameters: {
+      summary: { type: 'string', description: '可选的解决方案说明' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean', required: true },
+        },
+      },
+      render: () => [{ type: 'text', text: '冲突已标记为解决。' }],
+    },
+    async execute(_args, exec) {
+      const sessionId = exec.agent?.id
+      const cardId = resolver.cardOfSession(sessionId)
+      if (cardId === undefined) {
+        throw new Error('当前会话没有关联的任务卡片')
+      }
+      await resolver.mergeResolved(sessionId!)
+      exec.concludeTurn()
+      return { ok: true }
+    },
+  }))
+}

package/src/shared/card.ts

@@ -0,0 +1,115 @@
+/**
+ * Shared card/plan vocabulary used by both the server half (task store,
+ * runners) and the client half (board UI). Pure types: no runtime imports so
+ * it survives the client bundle's purity gate and gets inlined into both.
+ */
+
+export const CARD_SCHEMA_VERSION = 1
+
+/** Coarse card lifecycle status. */
+export type CardStatus =
+  | 'draft'
+  | 'refining'
+  | 'planned'
+  | 'queued'
+  | 'running'
+  | 'completed'
+  | 'merging'
+  | 'merged'
+  | 'error'
+
+/** Error kinds; each maps back to a resume action (retry/stop/delete). */
+export type ErrorKind =
+  | 'refine_failed'
+  | 'phase_failed'
+  | 'interrupted'
+  | 'merge_failed'
+  | 'no_base_branch'
+  | 'worktree_failed'
+  | 'create_failed'
+
+export interface CardError {
+  kind: ErrorKind
+  message: string
+  at: number
+  /** Lane the card was in when it failed (interrupted cards need this). */
+  stage?: Lane
+}
+
+/** One phase of a plan; phases execute strictly serially, each in its own session. */
+export interface PlanPhase {
+  id: string
+  title: string
+  goal: string
+}
+
+export interface Plan {
+  schemaVersion: number
+  title: string
+  summary: string
+  phases: PlanPhase[]
+}
+
+/** One session attempt of a phase (retries append new attempts). */
+export interface PhaseAttempt {
+  phaseIndex: number
+  sessionId: string
+  summary?: string
+  startedAt: number
+  completedAt?: number
+}
+
+/** Merge flow steps; retry resumes from the recorded step. */
+export type MergeStep = 'prepare' | 'wt-merge' | 'ws-merge' | 'pop' | 'cleanup'
+
+export interface MergeState {
+  step: MergeStep
+  stashApplied?: boolean
+  mergeCommit?: string
+}
+
+export interface KanbanCard {
+  schemaVersion: number
+  id: string
+  workspacePath: string
+  requirement: string
+  model: string
+  /** Provider route for the model (from the modal selection). */
+  provider?: string
+  status: CardStatus
+  error?: CardError
+  /** Git-mode: implementation happens in a worktree and merges back. */
+  gitMode?: boolean
+  baseRef?: string
+  baseSha?: string
+  branch?: string
+  worktreePath?: string
+  plan?: Plan
+  /** Index of the phase currently running / to resume from. */
+  currentPhase: number
+  phaseCount: number
+  sessions: {
+    refinement: string[]
+    phases: PhaseAttempt[]
+    merge: string[]
+  }
+  merge?: MergeState
+  queuedAt?: number
+  createdAt: number
+  stoppedAt?: number
+}
+
+/** The five board lanes. */
+export type Lane = 'demand' | 'queue' | 'running' | 'completed' | 'merged'
+
+/** Model entry for the new-task dropdown. */
+export interface ModelOption {
+  provider: string
+  id: string
+  name?: string
+}
+
+export interface KanbanSettingsShape {
+  maxParallelWorkers: number
+  defaultModel: string
+}

package/src/shared/lanes.ts

@@ -0,0 +1,43 @@
+/**
+ * Lane mapping and drag rules (shared by the board UI and tests).
+ */
+import type { KanbanCard, Lane } from './card.js'
+
+/** Which lane a card renders in, based on status + error stage. */
+export function laneOf(card: KanbanCard): Lane {
+  if (card.status === 'error') {
+    if (card.error?.stage !== undefined) return card.error.stage
+    const kind = card.error?.kind
+    if (kind === 'phase_failed' || kind === 'no_base_branch' || kind === 'worktree_failed') return 'running'
+    if (kind === 'merge_failed') return 'completed'
+    return 'demand'
+  }
+  switch (card.status) {
+    case 'draft':
+    case 'refining':
+    case 'planned':
+      return 'demand'
+    case 'queued':
+      return 'queue'
+    case 'running':
+      return 'running'
+    case 'completed':
+    case 'merging':
+      return 'completed'
+    case 'merged':
+      return 'merged'
+  }
+}
+
+/** Lanes a drop onto `to` may come from. */
+export const DROP_RULES: Record<Lane, Lane[]> = {
+  demand: ['queue'],
+  queue: ['demand', 'running'],
+  running: [],
+  completed: [],
+  merged: [],
+}
+
+export function canDrop(from: Lane, to: Lane): boolean {
+  return DROP_RULES[to].includes(from)
+}

package/src/shared/plan.ts

@@ -0,0 +1,54 @@
+/**
+ * Plan payload validation (shared by the write-back tool and tests).
+ */
+import type { Plan } from './card.js'
+
+export type ValidatePlanResult =
+  | { ok: true; plan: Plan }
+  | { ok: false; message: string }
+
+export function validatePlan(input: unknown): ValidatePlanResult {
+  if (typeof input !== 'object' || input === null) {
+    return { ok: false, message: '计划必须是对象' }
+  }
+  const obj = input as Record<string, unknown>
+  if (typeof obj.title !== 'string' || obj.title.trim() === '') {
+    return { ok: false, message: 'title 不能为空' }
+  }
+  if (typeof obj.summary !== 'string' || obj.summary.trim() === '') {
+    return { ok: false, message: 'summary 不能为空' }
+  }
+  if (!Array.isArray(obj.phases) || obj.phases.length === 0) {
+    return { ok: false, message: 'phases 必须是非空数组' }
+  }
+  const seen = new Set<string>()
+  for (const phase of obj.phases) {
+    if (typeof phase !== 'object' || phase === null) {
+      return { ok: false, message: 'phase 必须是对象' }
+    }
+    const p = phase as Record<string, unknown>
+    if (typeof p.id !== 'string' || typeof p.title !== 'string' || typeof p.goal !== 'string') {
+      return { ok: false, message: '每个 phase 都必须包含 id/title/goal' }
+    }
+    if (p.id.trim() === '' || p.title.trim() === '' || p.goal.trim() === '') {
+      return { ok: false, message: '每个 phase 的 id/title/goal 都不能为空' }
+    }
+    if (seen.has(p.id)) {
+      return { ok: false, message: `phase id 重复: ${p.id}` }
+    }
+    seen.add(p.id)
+  }
+  return {
+    ok: true,
+    plan: {
+      schemaVersion: 1,
+      title: obj.title,
+      summary: obj.summary,
+      phases: (obj.phases as Array<{ id: string; title: string; goal: string }>).map((p) => ({
+        id: p.id,
+        title: p.title,
+        goal: p.goal,
+      })),
+    },
+  }
+}