dsh-brief-sidebar 0.3.0

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "dsh-brief-sidebar",
+  "version": "0.3.0",
+  "description": "DSH web plugin (dsh-better-sidebar consumer): render the session brief — the todo list (the `todos` projection board) plus the artifact list (a live produced-files feed, codeplan artifacts marked) — as a summary tab in the right sidebar, and shadow the official composer-band todo panel so the board is the single visible carrier. Read-only.",
+  "type": "module",
+  "main": "lib/index.mjs",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.mjs"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src",
+    "cordis.patch.yml",
+    "dsh.plugin.json",
+    "README.md"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-locale"
+      ]
+    }
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "plugin",
+    "better-sidebar",
+    "brief",
+    "todo",
+    "artifact-list",
+    "task-board",
+    "summary",
+    "deliverables"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20",
+    "dsh": ">=0.1.5-rc.1 <0.2.0-0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "dsh-better-sidebar": ">=0.18.1",
+    "react": "^18.2.0"
+  },
+  "peerDependenciesMeta": {
+    "dsh-better-sidebar": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('lib',{recursive:true,force:true})\" && tsc -p tsconfig.build.json && tsdown --config-loader tsx",
+    "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.client.json",
+    "test": "vitest run",
+    "clean": "node -e \"require('node:fs').rmSync('lib',{recursive:true,force:true})\"",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@types/node": "^22.0.0",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.7",
+    "dsh-better-sidebar": "^0.19.1",
+    "jsdom": "^26.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "tsdown": "^0.22.2",
+    "tsx": "^4.23.12",
+    "typescript": "^5.6.0",
+    "vitest": "^3.0.0",
+    "zod": "^4.4.3"
+  }
+}

package/src/client/BriefIcon.tsx

@@ -0,0 +1,56 @@
+/**
+ * Tab glyph for the task board.
+ *
+ * Skin contract: plugin-drawn glyphs take their colour from the `--dsw-alias-*`
+ * tokens — no colour literals anywhere in this file.
+ */
+import type { ReactNode } from 'react'
+
+/**
+ * A checklist mark: three rows with ticks and text rails — the same status
+ * vocabulary the board paints.
+ * @param size - square edge in px (the host passes its own tab-icon size).
+ */
+export function BriefIcon(size: number): ReactNode {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 16 16"
+      fill="none"
+      aria-hidden="true"
+      focusable="false"
+      style={{ display: 'block', flex: 'none' }}
+    >
+      <rect
+        x={1.6}
+        y={2.4}
+        width={12.8}
+        height={11.2}
+        rx={2}
+        stroke="var(--dsw-alias-label-tertiary)"
+        strokeWidth={1.2}
+      />
+      <path
+        d="M4.2 6.1l1 1 1.8-2"
+        stroke="var(--dsw-alias-state-success-primary)"
+        strokeWidth={1.3}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+      <path
+        d="M4.2 10.6l1 1 1.8-2"
+        stroke="var(--dsw-alias-label-tertiary)"
+        strokeWidth={1.3}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+      <path
+        d="M8.4 6.4h4M8.4 10.9h4"
+        stroke="var(--dsw-alias-label-tertiary)"
+        strokeWidth={1.2}
+        strokeLinecap="round"
+      />
+    </svg>
+  )
+}

package/src/client/SummaryTab.tsx

@@ -0,0 +1,73 @@
+/**
+ * The summary tab body: the session's at-a-glance state, composed of sections.
+ *
+ * Section order: 进展 (the todos board) → 产物 (produced files, codeplan
+ * artifacts marked inline) → the reserved memory-recall slot (see below).
+ * Each section owns its own data chain and its own three-state contract; this
+ * component owns only the shell.
+ *
+ * Two better-sidebar contracts are honoured:
+ *
+ * 1. **Height contract.** The tab body mounts inside a full-height column flex
+ *    host whose `.paneBody` is a definite-height BLOCK scroll container. The
+ *    root declares `height: 100%` + `min-height: 0`, and the scrolling element
+ *    is an inner div — not the root. Sections are non-scrolling slices with a
+ *    bottom border; the inner div scrolls them all.
+ * 2. **`visible` pause.** Nothing is drawn while the tab is not the active
+ *    one, so a hidden tab does not re-render on every projection frame.
+ */
+import { createElement } from 'react'
+import type { CSSProperties, ReactNode } from 'react'
+import type { Context } from '@deepseek-ai/cordis'
+import { TodoSection } from './TodoBoardTab'
+import type { TodoScope } from './TodoBoardTab'
+import { DeliverablesSection } from './summary/DeliverablesSection'
+
+export interface SummaryTabProps {
+  /** The DSH locale lookup, passed down from `apply`. */
+  t: (key: string) => string
+  /** The client root context (the tab body's only way to reach services). */
+  ctx?: Context
+  /** The session this tab is scoped to. */
+  scope?: TodoScope
+  /** Whether the tab is the active one AND the panel is open. */
+  visible?: boolean
+}
+
+const ROOT_STYLE: CSSProperties = {
+  display: 'flex',
+  flexDirection: 'column',
+  height: '100%',
+  minHeight: 0,
+  background: 'var(--dsw-alias-bg-layer-1)',
+  color: 'var(--dsw-alias-label-primary)',
+  font: 'inherit',
+  fontSize: 13,
+}
+
+const SCROLL_STYLE: CSSProperties = { flex: 1, minHeight: 0, overflow: 'auto' }
+
+/**
+ * The summary tab.
+ * @param props - translation, client context, session scope, visibility.
+ */
+export function SummaryTab(props: SummaryTabProps): ReactNode {
+  const { t, ctx, scope, visible = true } = props
+
+  // A hidden tab renders NOTHING — not even the shell — so it never
+  // re-renders on a projection frame while it is off screen.
+  if (!visible) return null
+
+  return createElement(
+    'div',
+    { style: ROOT_STYLE, 'data-dsh-brief-sidebar': 'board' },
+    createElement('div', { style: SCROLL_STYLE },
+      createElement(TodoSection, { key: 'progress', t, ctx, scope }),
+      createElement(DeliverablesSection, { key: 'deliverables', t, ctx, scope }),
+      // 记忆召回插槽（远期，固定最底）：概要从两区扩为三区时，记忆召回分区
+      // 排在这里。系统中没有默认记忆，数据链等记忆类插件注册自己的投影 key
+      // 后经同一个 `faceOf` 通道接入（`useProjectionValue`），本期不渲染。
+      null,
+    ),
+  )
+}

package/src/client/TodoBoardTab.tsx

@@ -0,0 +1,188 @@
+/**
+ * The progress section: the `todos` projection drawn as one part of the
+ * summary tab.
+ *
+ * The official composer-band panel is shadowed by this plugin (see
+ * `brief/dock-shadow.tsx`), so the projection is read here and rendered as an
+ * ordinary React view — no Canvas, no cross-package dependency. The full-height
+ * shell and the scroll container live on the summary tab (`../SummaryTab`);
+ * this component renders only its own slice and is the one section whose
+ * absent state must stay VISIBLE: the official dock is hidden while this
+ * plugin is mounted, so "unavailable" is a statement the reader needs.
+ *
+ * Colours come from `--dsw-alias-*` tokens only (skin contract), and the status
+ * palette uses tokens that actually exist in the shipping theme:
+ * `state-success-primary` / `state-business-primary` / `label-tertiary`.
+ */
+import { createElement } from 'react'
+import type { CSSProperties, ReactNode } from 'react'
+import type { Context } from '@deepseek-ai/cordis'
+import { countTodos, progressLine, statusKey } from './brief/board'
+import type { TodoItem, TodoStatus } from './brief/board'
+import { useTodos } from './brief/use-todos'
+
+/** The session scope better-sidebar hands a tab body. */
+export interface TodoScope {
+  readonly sessionId?: string
+}
+
+export interface TodoSectionProps {
+  /** The DSH locale lookup, passed down from `apply`. */
+  t: (key: string) => string
+  /** The client root context (the tab body's only way to reach services). */
+  ctx?: Context
+  /** The session this tab is scoped to. */
+  scope?: TodoScope
+}
+
+/** Status → token colour for the pill's text and border. */
+const STATUS_COLOR: Record<TodoStatus, string> = {
+  completed: 'var(--dsw-alias-state-success-primary)',
+  in_progress: 'var(--dsw-alias-state-business-primary)',
+  pending: 'var(--dsw-alias-label-tertiary)',
+}
+
+const SECTION_STYLE: CSSProperties = {
+  flexShrink: 0,
+  borderBottom: '1px solid var(--dsw-alias-border-secondary)',
+}
+
+const HEADER_STYLE: CSSProperties = {
+  padding: '10px 12px 0',
+  color: 'var(--dsw-alias-label-secondary)',
+  fontSize: 12,
+  fontWeight: 600,
+}
+
+const PROGRESS_STYLE: CSSProperties = {
+  padding: '6px 12px 10px',
+  color: 'var(--dsw-alias-label-secondary)',
+  fontSize: 12,
+}
+
+const LIST_STYLE: CSSProperties = {
+  listStyle: 'none',
+  margin: 0,
+  padding: '6px 0',
+  display: 'flex',
+  flexDirection: 'column',
+}
+
+const ROW_STYLE: CSSProperties = {
+  display: 'flex',
+  alignItems: 'flex-start',
+  gap: 8,
+  padding: '6px 12px',
+}
+
+/** Pill style, coloured per status. */
+function pillStyle(status: TodoStatus): CSSProperties {
+  return {
+    flexShrink: 0,
+    color: STATUS_COLOR[status],
+    border: `1px solid ${STATUS_COLOR[status]}`,
+    borderRadius: 999,
+    padding: '0 6px',
+    fontSize: 11,
+    lineHeight: '16px',
+    whiteSpace: 'nowrap',
+  }
+}
+
+/** Task text: finished entries read as done, the working one as active. */
+function contentStyle(status: TodoStatus): CSSProperties {
+  return {
+    minWidth: 0,
+    overflowWrap: 'anywhere',
+    color:
+      status === 'completed'
+        ? 'var(--dsw-alias-label-tertiary)'
+        : status === 'in_progress'
+          ? 'var(--dsw-alias-label-primary)'
+          : 'var(--dsw-alias-label-secondary)',
+    textDecoration: status === 'completed' ? 'line-through' : 'none',
+  }
+}
+
+/** Centred message block used by every non-list state. */
+export function Notice(props: { title: string; detail?: string }): ReactNode {
+  return (
+    <div
+      style={{
+        margin: '0 auto',
+        padding: 24,
+        maxWidth: 460,
+        textAlign: 'center',
+        color: 'var(--dsw-alias-label-tertiary)',
+        lineHeight: 1.7,
+        fontSize: 12,
+      }}
+    >
+      <div style={{ marginBottom: 6, color: 'var(--dsw-alias-label-secondary)' }}>{props.title}</div>
+      {props.detail === undefined ? null : <div>{props.detail}</div>}
+    </div>
+  )
+}
+
+/** One task row. */
+function TodoRow(props: { item: TodoItem; t: (key: string) => string }): ReactNode {
+  const { item, t } = props
+  return createElement(
+    'li',
+    { style: ROW_STYLE },
+    createElement('span', { style: pillStyle(item.status) }, t(statusKey(item.status))),
+    createElement('span', { style: contentStyle(item.status) }, item.content),
+  )
+}
+
+/**
+ * The progress section. The subscription is unconditional (a plain listener,
+ * not IO); the three-state contract of the projection is preserved verbatim.
+ * @param props - translation, client context, session scope.
+ */
+export function TodoSection(props: TodoSectionProps): ReactNode {
+  const { t, ctx, scope } = props
+
+  const todos = useTodos(ctx, scope?.sessionId)
+
+  if (todos === undefined) {
+    // `undefined` is the store's "capability absent": no session, or the host's
+    // todo unit is unmounted. Say so rather than showing an empty board.
+    return createElement(
+      'div',
+      { style: SECTION_STYLE, 'data-dsh-brief-sidebar': 'progress-section' },
+      createElement('div', { style: HEADER_STYLE }, t('section.progress')),
+      createElement(Notice, { title: t('board.unavailable'), detail: t('board.unavailableHint') }),
+    )
+  }
+
+  if (todos.length === 0) {
+    return createElement(
+      'div',
+      { style: SECTION_STYLE, 'data-dsh-brief-sidebar': 'progress-section' },
+      createElement('div', { style: HEADER_STYLE }, t('section.progress')),
+      createElement(Notice, { title: t('board.empty'), detail: t('board.emptyHint') }),
+    )
+  }
+
+  const counts = countTodos(todos)
+
+  return createElement(
+    'div',
+    { style: SECTION_STYLE, 'data-dsh-brief-sidebar': 'progress-section' },
+    createElement('div', { style: HEADER_STYLE }, t('section.progress')),
+    createElement('div', { style: PROGRESS_STYLE }, progressLine(counts, t)),
+    createElement(
+      'ul',
+      { style: LIST_STYLE },
+      todos.map((item, index) => createElement(TodoRow, { key: `${index}:${item.content}`, item, t })),
+    ),
+  )
+}
+
+/**
+ * Backwards-compatible alias for the pre-summary export name. The component
+ * no longer owns the full-height shell — that moved to `SummaryTab` — so the
+ * alias exists only to keep import sites honest during the transition.
+ */
+export const TodoBoardTab = TodoSection

package/src/client/brief/board.ts

@@ -0,0 +1,104 @@
+/**
+ * The `todos` projection — reading and classifying it.
+ *
+ * The Host computes this projection (`dsh-tool-todo` registers the key) and
+ * pushes finished whole values; the client never folds it. This module is the
+ * read side of that contract and is deliberately PURE — no React, no context,
+ * no IO — so the mapping can be tested directly.
+ */
+/** The projection's three-state lifecycle (`TodoItem` in `dsh-tool-todo`). */
+export type TodoStatus = 'pending' | 'in_progress' | 'completed'
+
+/** One entry of the `todos` projection. */
+export interface TodoItem {
+  readonly content: string
+  readonly status: TodoStatus
+}
+
+const STATUSES: readonly TodoStatus[] = ['pending', 'in_progress', 'completed']
+
+/** Locale key per status. Kept here so this module owns the vocabulary. */
+const STATUS_KEY: Record<TodoStatus, string> = {
+  pending: 'status.pending',
+  in_progress: 'status.inProgress',
+  completed: 'status.completed',
+}
+
+/** Locale key for one status label. */
+export function statusKey(status: TodoStatus): string {
+  return STATUS_KEY[status]
+}
+
+/**
+ * Narrow a raw projection value into a todo list.
+ *
+ * Three outcomes are kept apart on purpose, mirroring the store's own contract:
+ * - `undefined` — the capability is ABSENT (no session, the host unit is
+ *   unmounted, or no baseline/frame has carried the key yet);
+ * - `[]` — the projection is present and the list is empty (`null` on the wire);
+ * - a list — real entries.
+ *
+ * A malformed entry is dropped rather than thrown on: the projection is a
+ * trusted Host value, but a shape drift must not blank the whole board.
+ *
+ * @param value - the raw `unknown` snapshot of the `todos` face.
+ * @returns the validated list, or `undefined` when the capability is absent.
+ */
+export function readTodos(value: unknown): readonly TodoItem[] | undefined {
+  if (value === null) return []
+  if (!Array.isArray(value)) return undefined
+
+  const items: TodoItem[] = []
+  for (const raw of value) {
+    if (raw === null || typeof raw !== 'object') continue
+    const { content, status } = raw as { content?: unknown; status?: unknown }
+    if (typeof content !== 'string') continue
+    if (typeof status !== 'string' || !isStatus(status)) continue
+    items.push({ content, status })
+  }
+  return items
+}
+
+/** Whether a string is one of the three lifecycle values. */
+function isStatus(value: string): value is TodoStatus {
+  return (STATUSES as readonly string[]).includes(value)
+}
+
+/** Per-status counts over one list. */
+export interface TodoCounts {
+  readonly total: number
+  readonly completed: number
+  readonly inProgress: number
+  readonly pending: number
+}
+
+/** Count a todo list by status. */
+export function countTodos(todos: readonly TodoItem[]): TodoCounts {
+  let completed = 0
+  let inProgress = 0
+  let pending = 0
+  for (const item of todos) {
+    if (item.status === 'completed') completed += 1
+    else if (item.status === 'in_progress') inProgress += 1
+    else pending += 1
+  }
+  return { total: todos.length, completed, inProgress, pending }
+}
+
+/** How many entries are not finished — the tab badge. */
+export function unfinishedCount(todos: readonly TodoItem[]): number {
+  const counts = countTodos(todos)
+  return counts.inProgress + counts.pending
+}
+
+/**
+ * The one-line progress summary, composed from parts so no interpolation
+ * machinery is needed (the locale binder is a plain key → string lookup).
+ * Mirrors the official dock's own label.
+ */
+export function progressLine(counts: TodoCounts, t: (key: string) => string): string {
+  const parts = [`${t('status.completed')} ${counts.completed}/${counts.total}`]
+  if (counts.inProgress > 0) parts.push(`${t('status.inProgress')} ${counts.inProgress}`)
+  if (counts.pending > 0) parts.push(`${t('status.pending')} ${counts.pending}`)
+  return parts.join(' · ')
+}

package/src/client/brief/dock-shadow.tsx

@@ -0,0 +1,74 @@
+/**
+ * Hiding the official todo dock.
+ *
+ * `conversation.input.dock` is a LIST slot, and its cells are keyed by each
+ * entry's `id`. The slot core keeps one live entry per cell — entries are
+ * sorted by `priority` ascending (then by `order`) and the first live entry of
+ * a cell is the one the outlet renders, so a SECOND registration with the same
+ * `id` at a LOWER priority shadows the first. The official todo entry
+ * (`conversation-todo-dock` in `dsh-client-ui-conversation`) registers
+ * `{ id: 'todo', order: 0 }` with the default priority 0, so
+ * `{ id: 'todo', priority: -1 }` wins the cell and the official panel never
+ * renders while this plugin is mounted.
+ *
+ * This is the same mechanism `dsh-input-traffic` uses on the sibling `queue`
+ * cell (`{ id: 'queue', priority: -1 }`), so it is a proven seam on this host
+ * generation, not a guess.
+ *
+ * Binding to a built-in id is a real coupling: if upstream renames the cell,
+ * the shadow silently stops winning and the official dock simply reappears
+ * (fail-open — the data is still shown, just twice). `slots.inject` is used
+ * rather than a bare `register` because the slot is declared by a built-in
+ * entry whose lifetime we do not control: `inject` waits for the declaration
+ * and re-installs the entry if the declaration is ever recreated.
+ *
+ * Renders nothing on purpose: the todo UI now lives in this plugin's sidebar
+ * tab. Return a summary chip here instead to keep a one-line entry point in the
+ * composer band.
+ */
+import type { ReactNode } from 'react'
+import type { Context } from '@deepseek-ai/cordis'
+
+/** The built-in cell id of the official todo dock. */
+export const TODO_CELL_ID = 'todo'
+
+/** Lower than the built-in's default 0 — the winner of the `todo` cell. */
+export const TODO_SHADOW_PRIORITY = -1
+
+/** Structural view of the client slots service (avoids a second type graph). */
+export interface SlotsLike {
+  inject(key: string, callback: () => (() => void) | undefined): () => void
+  register(options: Record<string, unknown>, component: (props: unknown) => ReactNode): () => void
+}
+
+/** The replacement entry: deliberately empty. */
+function TodoDockShadow(): ReactNode {
+  return null
+}
+
+/**
+ * Register the shadowing entry.
+ *
+ * The caller wraps this in `ctx.effect(...)` so the returned disposer rides the
+ * plugin fiber: unloading the plugin restores the official dock.
+ *
+ * @param ctx - the client root context.
+ * @returns the disposer, or undefined when the slots service is unreachable.
+ */
+export function registerTodoDockShadow(ctx: Context): (() => void) | undefined {
+  const slots = ctx.get('slots') as SlotsLike | undefined
+  if (slots === undefined || typeof slots.inject !== 'function') return undefined
+
+  return slots.inject('conversation.input.dock', () =>
+    slots.register(
+      {
+        name: 'conversation.input.dock',
+        id: TODO_CELL_ID,
+        order: 0,
+        priority: TODO_SHADOW_PRIORITY,
+        registrant: 'dsh-brief-sidebar',
+      },
+      TodoDockShadow,
+    ),
+  )
+}

package/src/client/brief/use-todos.ts

@@ -0,0 +1,27 @@
+/**
+ * Reading the live `todos` projection — the thin, todo-specific wrapper around
+ * the generic face resolver (`../use-projection`). The projection key is
+ * registered by `dsh-tool-todo`; the host pushes finished whole values and the
+ * client never folds it. Narrowing lives in `./board` (`readTodos`).
+ */
+import { useMemo } from 'react'
+import type { Context } from '@deepseek-ai/cordis'
+import { readTodos } from './board'
+import type { TodoItem } from './board'
+import { useProjectionValue } from '../use-projection'
+
+/** The projection key registered by `dsh-tool-todo`. */
+export const TODOS_KEY = 'todos'
+
+/**
+ * Subscribe to one session's todo list.
+ *
+ * @param ctx - the client root context.
+ * @param sessionId - the session whose projection is shown.
+ * @returns the list, `[]` for a present-but-empty projection, or `undefined`
+ *   while the capability is absent.
+ */
+export function useTodos(ctx: Context | undefined, sessionId: string | undefined): readonly TodoItem[] | undefined {
+  const raw = useProjectionValue(ctx, sessionId, TODOS_KEY)
+  return useMemo(() => readTodos(raw), [raw])
+}