@fonlan/dsh-task-kanban 0.1.0

package/lib/types/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @fonlan/dsh-task-kanban host half: the task kanban engine.
+ *
+ * Mounts a file-backed task store under each workspace's
+ * `.dsh/task-kanban/`, runs refinement/phase/merge sessions through
+ * `ctx.agents` (standard coding-agent preset + kanban-scoped tools), and
+ * serves the fenced JSON API the board UI calls.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export declare const name = "@fonlan/dsh-task-kanban";
+export declare const inject: string[];
+export declare const Config: z<Schemastery.ObjectS<{}>, Schemastery.ObjectT<{}>>;
+export declare function apply(ctx: Context, _config: unknown): void;

package/lib/types/server/git.d.ts

@@ -0,0 +1,16 @@
+export interface GitResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+export declare function runGit(cwd: string, args: string[]): Promise<GitResult>;
+export declare function isGitRepo(dir: string): Promise<boolean>;
+export declare function hasBranch(dir: string, name: string): Promise<boolean>;
+export declare function detectBaseRef(dir: string): Promise<string | undefined>;
+export declare function currentBranch(dir: string): Promise<string | undefined>;
+export declare function revParse(dir: string, ref: string): Promise<string | undefined>;
+/** True when the working tree has tracked changes (staged or unstaged). */
+export declare function isTreeDirty(dir: string): Promise<boolean>;
+export declare function hasStashMessage(dir: string, message: string): Promise<boolean>;
+/** Unmerged path list after a conflicted merge (empty when clean). */
+export declare function unmergedPaths(dir: string): Promise<string>;

package/lib/types/server/models.d.ts

@@ -0,0 +1,4 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { ModelOption } from '../shared/card.js';
+/** Available models from every registered LLM provider (advisory catalog). */
+export declare function listModels(ctx: Context): Promise<ModelOption[]>;

package/lib/types/server/prompts.d.ts

@@ -0,0 +1,7 @@
+import type { KanbanCard } from '../shared/card.js';
+/** Refinement session prompt: analyze the repo read-only and write back a plan. */
+export declare function refinementPrompt(requirement: string, workspacePath: string): string;
+/** Phase implementation session prompt; identical on retries (the model reads git status/diff itself). */
+export declare function phasePrompt(card: KanbanCard, phaseIndex: number, workdir: string): string;
+/** Merge-conflict resolution session prompt: resolve conflicts only, never commit. */
+export declare function mergePrompt(workdir: string, conflicts: string): string;

package/lib/types/server/rpc.d.ts

@@ -0,0 +1,4 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { KanbanRunner } from './runner.js';
+import type { KanbanSettingsFace } from './settings.js';
+export declare function registerApiRoutes(ctx: Context, runner: KanbanRunner, settings: KanbanSettingsFace): () => void;

package/lib/types/server/runner.d.ts

@@ -0,0 +1,84 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { KanbanCard, Lane, Plan } from '../shared/card.js';
+import type { TaskStore } from './task-store.js';
+import type { KanbanSettingsFace } from './settings.js';
+import { type KanbanToolResolver } from './tools.js';
+export declare class KanbanRunner implements KanbanToolResolver {
+    private ctx;
+    private store;
+    private settings;
+    private runningByWs;
+    private slots;
+    private pumpTimer;
+    /** sessionId → cardId (sessions created for this kanban). */
+    private sessionCards;
+    /** sessionId → true once the scoped completion tool ran. */
+    private completed;
+    private merging;
+    /** Retained agent handles (kept so ended sessions stay in the store/UI). */
+    private handles;
+    constructor(ctx: Context, store: TaskStore, settings: KanbanSettingsFace);
+    register(ctx: Context): void;
+    start(): void;
+    stop(): void;
+    private newSessionId;
+    private asUserMessage;
+    private workspaceList;
+    cardOfSession(sessionId?: string): string | undefined;
+    writePlan(cardId: string, plan: Plan): Promise<void>;
+    phaseComplete(sessionId: string, summary: string): Promise<string>;
+    mergeResolved(sessionId: string): Promise<void>;
+    private toolResolver;
+    recoverInterrupted(): Promise<void>;
+    listCards(workspacePath: string): Promise<KanbanCard[]>;
+    createTask(input: {
+        workspacePath: string;
+        requirement: string;
+        model: string;
+        provider?: string;
+    }): Promise<KanbanCard>;
+    moveTask(cardId: string, toLane: Lane): Promise<{
+        ok: boolean;
+        message?: string;
+    }>;
+    stopTask(cardId: string): Promise<{
+        ok: boolean;
+        message?: string;
+    }>;
+    retryTask(cardId: string): Promise<{
+        ok: boolean;
+        message?: string;
+    }>;
+    deleteTask(cardId: string): Promise<{
+        ok: boolean;
+        message?: string;
+    }>;
+    private findCard;
+    private maxParallel;
+    pump(): Promise<void>;
+    private requestStop;
+    private fail;
+    private runRefinement;
+    private createAgent;
+    private keepHandle;
+    /**
+     * Account the refinement session to its host workspace so it shows in that
+     * workspace's session list. The session's cwd IS the workspace root, so the
+     * registry's strict `cwd === workspace.path` check passes. Best-effort only:
+     * an unregistered workspace (or a failing registry) must not break the card.
+     */
+    private attachRefinementSession;
+    /** The host workspace registry, whichever service name carries it. */
+    private attachRegistry;
+    /** Resolve the provider+model route for an agent (both are required). */
+    private modelRoute;
+    private runCard;
+    private runPhase;
+    private resolveConflictsIn;
+    /** Check resolved files for leftover conflict markers. */
+    private verifyConflictMarkers;
+    runMerge(cardId: string, wsPath: string): Promise<boolean>;
+    private mergeCard;
+    private runMergeSession;
+    private ensureGitignoreDsh;
+}

package/lib/types/server/settings.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 type { KanbanSettingsShape } from '../shared/card.js';
+export declare const KANBAN_SETTINGS_NS: import("@deepseek-ai/dsh-settings").SettingsNamespace;
+export declare const KanbanSettingsSchema: z<Schemastery.ObjectS<{
+    maxParallelWorkers: z<number, number>;
+    defaultModel: z<string, string>;
+}>, Schemastery.ObjectT<{
+    maxParallelWorkers: z<number, number>;
+    defaultModel: z<string, string>;
+}>>;
+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;
+    };
+}
+export declare function registerSettings(ctx: Context): KanbanSettingsFace;

package/lib/types/server/task-store.d.ts

@@ -0,0 +1,27 @@
+import { type KanbanCard } from '../shared/card.js';
+/**
+ * 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 declare class TaskStore {
+    private cache;
+    private locks;
+    private taskDir;
+    private fileOf;
+    private withLock;
+    list(workspacePath: string): Promise<KanbanCard[]>;
+    get(workspacePath: string, id: string): Promise<KanbanCard | undefined>;
+    create(input: {
+        workspacePath: string;
+        requirement: string;
+        model: string;
+        provider?: string;
+        status?: KanbanCard['status'];
+    }): Promise<KanbanCard>;
+    /** Run a mutation under the card's lock; returns the updated card. */
+    mutate(id: string, fn: (card: KanbanCard) => void | Promise<void>, workspacePath?: string): Promise<KanbanCard | undefined>;
+    private write;
+    remove(workspacePath: string, id: string): Promise<void>;
+}

package/lib/types/server/tools.d.ts

@@ -0,0 +1,11 @@
+import type { Context } from '@deepseek-ai/cordis';
+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 declare function registerKanbanTools(agentCtx: Context, resolver: KanbanToolResolver): void;

package/lib/types/shared/card.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 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 declare 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/lib/types/shared/lanes.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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 declare function laneOf(card: KanbanCard): Lane;
+/** Lanes a drop onto `to` may come from. */
+export declare const DROP_RULES: Record<Lane, Lane[]>;
+export declare function canDrop(from: Lane, to: Lane): boolean;

package/lib/types/shared/plan.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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 declare function validatePlan(input: unknown): ValidatePlanResult;

package/package.json

@@ -0,0 +1,105 @@
+{
+  "name": "@fonlan/dsh-task-kanban",
+  "version": "0.1.0",
+  "description": "DSH web plugin: a task kanban that refines requirements into phased plans, auto-executes them in git worktrees (one session per phase), and auto-merges into the main branch on completion.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fonlan/dsh-task-kanban.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fonlan/dsh-task-kanban/issues"
+  },
+  "homepage": "https://github.com/fonlan/dsh-task-kanban",
+  "keywords": [
+    "dsh",
+    "kanban",
+    "plugin",
+    "task-management",
+    "worktree"
+  ],
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "rm -rf lib && tsc -p tsconfig.build.json && tsdown",
+    "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.client.json",
+    "bundle": "tsdown",
+    "watch": "tsdown --watch",
+    "test": "vitest run"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-client-ui-primitives",
+        "@deepseek-ai/dsh-client-ui-sidebar",
+        "@deepseek-ai/dsh-client-ui-layout",
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-web-react"
+      ]
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-agent-presets": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.6",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.0-rc.6",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.0",
+    "tsdown": "^0.22.14",
+    "typescript": "^5.9.0",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-agent-presets": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.6",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-sidebar": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-layout": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.0-rc.6",
+    "vitest": "^3.2.0"
+  },
+  "packageManager": "pnpm@11.21.0"
+}

package/src/client/api.ts

@@ -0,0 +1,42 @@
+import type { KanbanCard, KanbanSettingsShape, Lane, ModelOption } from '../shared/card'
+
+export class KanbanApiError extends Error {
+  constructor(readonly code: string, message: string) {
+    super(message)
+  }
+}
+
+async function call<T>(method: string, payload: Record<string, unknown> = {}): Promise<T> {
+  let response: Response
+  try {
+    response = await fetch(`/plugins/@fonlan/dsh-task-kanban/api/${method}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(payload),
+    })
+  } catch (error) {
+    throw new KanbanApiError('network', error instanceof Error ? error.message : String(error))
+  }
+  const parsed: { ok?: boolean; value?: unknown; error?: { code?: string; message?: string } } | null
+    = await response.json().catch(() => null)
+  if (!response.ok || parsed === null || parsed.ok !== true || parsed.value === undefined) {
+    throw new KanbanApiError(
+      parsed?.error?.code ?? 'http',
+      parsed?.error?.message ?? `HTTP ${response.status}`,
+    )
+  }
+  return parsed.value as T
+}
+
+export const api = {
+  list: (workspacePath: string) => call<KanbanCard[]>('list', { workspacePath }),
+  create: (workspacePath: string, requirement: string, model: string, provider?: string) =>
+    call<KanbanCard>('create', { workspacePath, requirement, model, provider }),
+  move: (cardId: string, toLane: Lane) => call<{ ok: boolean; message?: string }>('move', { cardId, toLane }),
+  stop: (cardId: string) => call<{ ok: boolean; message?: string }>('stop', { cardId }),
+  retry: (cardId: string) => call<{ ok: boolean; message?: string }>('retry', { cardId }),
+  remove: (cardId: string) => call<{ ok: boolean; message?: string }>('remove', { cardId }),
+  settingsGet: () => call<KanbanSettingsShape>('settings.get'),
+  settingsSet: (patch: Partial<KanbanSettingsShape>) => call<KanbanSettingsShape>('settings.set', patch),
+  models: () => call<ModelOption[]>('models.list'),
+}