@alpacachen/dsh-kanban 1.8.0 → 1.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -126,6 +126,8 @@ For `kanban_add_card` and `kanban_update_card`, the task description uses the ex
126
126
 
127
127
  For due dates, `kanban_add_card` and `kanban_update_card` accept `dueDate` as a real calendar date in `YYYY-MM-DD` format. Omit it to keep the current date (new cards default to none); use `null` or an empty string to clear it. Dates have no time or timezone: a task due today becomes overdue the next local calendar day. Resolve phrases such as “this Friday” against the user's local date and confirm the concrete date instead of sending relative text or a UTC timestamp. Both `kanban_get` and `kanban_get_card` return the date and the board's `completedColumnId`.
128
128
 
129
+ Completion dates are recorded automatically when a card enters the configured completion list (including creation there). Reopening clears the date; completing again records a new timestamp. Edits, comments, same-list sorting, and column renames/reordering preserve it. Card details show the local completion time next to the due date; it is read-only. Both read tools return `completedAt` as a UTC ISO timestamp, or `null`. A completed card with `null` has an unknown completion time. Changing or clearing the completion list resets completion dates; existing cards in the newly selected list have unknown dates. Deleting a list applies the same completion rules to its automatic card moves. Schema v5 migration backs up the original file and leaves historical completion times unknown rather than guessing from truncated, title-based activity history.
130
+
129
131
  Use `kanban_set_completed_column` with an existing `columnId` to designate the finished stage, or `null` to clear it. New boards use their default Done column; existing boards need an explicit choice. Completion follows the column ID through renames and reordering, and deleting that column clears the setting. Cards in the completion column keep their dates but are excluded from **Due today** and **Overdue** filters; moving them out resumes date checks. There are no automatic reminders or date-based reordering.
130
132
 
131
133
  > Set the payment integration task's due date to this Friday, then show me unfinished tasks that are due today or overdue so I can decide what to tackle first.
package/README.zh.md CHANGED
@@ -124,6 +124,8 @@ dsh --profile web --dump-config
124
124
 
125
125
  `kanban_add_card` 和 `kanban_update_card` 的任务描述仍使用 `note` 字段,传入保留换行的 Markdown 原文,不传 HTML。任务详情会渲染标题、列表、表格和代码块。原文最多 2,000 字符,Markdown 标记和换行也计入长度,超出会截断并返回警告。修改已有描述前,应先调用 `kanban_get_card` 读取完整原文(`kanban_get` 只返回摘要)。传入 `note` 会替换整段描述;省略则保留原文,传空字符串则清空。评论仍为纯文本。
126
126
 
127
+ 完成日期在卡片进入完成列时自动记录(包括直接在完成列创建),移出时清空,再次完成时记录新时间。修改内容、评论、同列排序和列改名/排序不影响完成日期。卡片详情在截止日期旁以本地时区只读展示;两个读取工具均返回 UTC ISO 时间戳 `completedAt` 或 `null`,已完成卡片的 `null` 表示时间未知。更换或清除完成列会重置完成时间,新完成列中已有卡片显示未知;删除列引发自动移动时也遵循进入/离开完成状态的规则。升级至数据格式 v5 时会备份原文件,历史完成时间保留未知,不依据可能被截断、按列名记录的活动日志推测。
128
+
127
129
  `kanban_add_card` 和 `kanban_update_card` 可通过 `dueDate` 设置截止日期,值为真实有效的 `YYYY-MM-DD` 日期。省略则保留原日期(新卡片默认为无日期),传 `null` 或空字符串则清空。日期不含时间和时区:今天到期的任务到本地次日才算逾期。「本周五」等相对日期应由 Agent 按用户本地日期换算,并向用户确认具体日期,不要直接传相对文本或 UTC 时间戳。`kanban_get` 和 `kanban_get_card` 都会返回截止日期与看板的 `completedColumnId`。
128
130
 
129
131
  使用 `kanban_set_completed_column`,传已有的 `columnId` 指定完成列,传 `null` 清除设置。新看板默认使用 Done,已有看板需要明确选择一次。设置跟随列 ID,改名和排序不影响;删除完成列会清除设置。完成列中的卡片保留日期,但不计入「今天到期」和「已逾期」筛选,移回其他列后恢复判断。暂不包含自动提醒和按日期自动排序。
package/index.js CHANGED
@@ -11,11 +11,11 @@
11
11
  * - Browser API: ctx.get('connection') registers the authenticated /api/kanban route.
12
12
  *
13
13
  * Per-workspace data model (disk files include schemaVersion):
14
- * schemaVersion: 4
14
+ * schemaVersion: 5
15
15
  * completedColumnId: string | null
16
16
  * columns: [{ id, title }]
17
17
  * labels: [{ name, color }] // name is the unique key and binds the color
18
- * cards: [{ id, columnId, title, note, label, priority, dueDate, createdAt, createdBy,
18
+ * cards: [{ id, columnId, title, note, label, priority, dueDate, completedAt, createdAt, createdBy,
19
19
  * comments: [{ id, content, source, createdAt }] }]
20
20
  * activities: [{ id, ts, cardId, type, source, field?, from?, to?, meta? }] // append-only log
21
21
  *
@@ -46,7 +46,7 @@ export const inject = ['tools']
46
46
  // Back up old files before following the migration chain on first access.
47
47
  // ---------------------------------------------------------------------------
48
48
 
49
- export const SCHEMA_VERSION = 4
49
+ export const SCHEMA_VERSION = 5
50
50
  export const LEGACY_VERSION = 0
51
51
 
52
52
  // Append-only activity log persisted with the board; drop oldest events above the limit.
@@ -145,6 +145,12 @@ export const MIGRATIONS = {
145
145
  completedColumnId: null,
146
146
  cards: Array.isArray(data.cards) ? data.cards.map((card) => isObj(card) ? { ...card, dueDate: null } : card) : data.cards,
147
147
  }),
148
+ 4: (data) => ({
149
+ ...data,
150
+ schemaVersion: 5,
151
+ // Truncated, title-based activity history cannot reliably recover completion times.
152
+ cards: Array.isArray(data.cards) ? data.cards.map((card) => isObj(card) ? { ...card, completedAt: null } : card) : data.cards,
153
+ }),
148
154
  }
149
155
 
150
156
  /**
@@ -235,6 +241,8 @@ export function validateBoard(data) {
235
241
  if (!columnIds.has(c.columnId)) errors.push('card references missing column: ' + c.id)
236
242
  if (c.label != null && !labelNames.has(c.label)) errors.push('card references missing label: ' + c.id)
237
243
  if (c.dueDate !== null && !isDueDate(c.dueDate)) errors.push('card has invalid due date: ' + c.id)
244
+ if (c.completedAt !== null && (typeof c.completedAt !== 'string' || !Number.isFinite(Date.parse(c.completedAt)) || new Date(c.completedAt).toISOString() !== c.completedAt)) errors.push('card has invalid completion time: ' + c.id)
245
+ if (c.completedAt !== null && c.columnId !== data.completedColumnId) errors.push('incomplete card has a completion time: ' + c.id)
238
246
  if (c.priority != null && !['high', 'medium', 'low'].includes(c.priority)) errors.push('card has invalid priority: ' + c.id)
239
247
  for (const comment of c.comments) {
240
248
  if (!isObj(comment) || typeof comment.id !== 'string' || !comment.id || typeof comment.content !== 'string' || !comment.content.trim() || comment.content.length > 2000 || !['human', 'agent'].includes(comment.source) || typeof comment.createdAt !== 'string' || !comment.createdAt) {
@@ -595,6 +603,7 @@ export function apply(ctx) {
595
603
  label: c.label ?? null,
596
604
  priority: c.priority ?? null,
597
605
  dueDate: c.dueDate,
606
+ completedAt: c.completedAt,
598
607
  createdAt: typeof c.createdAt === 'string' ? c.createdAt : null,
599
608
  createdBy: typeof c.createdBy === 'string' ? c.createdBy : null,
600
609
  comments: Array.isArray(c.comments)
@@ -623,6 +632,7 @@ export function apply(ctx) {
623
632
  label: c.label ?? null,
624
633
  priority: c.priority ?? null,
625
634
  dueDate: c.dueDate,
635
+ completedAt: c.completedAt,
626
636
  commentCount: c.comments.length,
627
637
  })),
628
638
  })
@@ -680,6 +690,7 @@ export function apply(ctx) {
680
690
  createdBy: actor,
681
691
  comments: [],
682
692
  }
693
+ card.completedAt = col.id === board.completedColumnId ? card.createdAt : null
683
694
  board.cards.push(card)
684
695
  record(board, {
685
696
  cardId: card.id,
@@ -778,7 +789,9 @@ export function apply(ctx) {
778
789
  if (!card || !target) return result({ error: 'Card or list not found' })
779
790
  const fromCol = findColumn(board, card.columnId)
780
791
  const fromTitle = fromCol ? fromCol.title : String(card.columnId)
792
+ const changedColumn = card.columnId !== target.id
781
793
  board.cards = board.cards.filter((c) => c.id !== card.id)
794
+ if (changedColumn) card.completedAt = target.id === board.completedColumnId ? new Date().toISOString() : null
782
795
  card.columnId = target.id
783
796
  const inCol = board.cards.filter((c) => c.columnId === target.id)
784
797
  const toIndex = typeof a.toIndex === 'number' && Number.isFinite(a.toIndex)
@@ -787,7 +800,7 @@ export function apply(ctx) {
787
800
  const anchor = inCol[toIndex]
788
801
  if (anchor) board.cards.splice(board.cards.indexOf(anchor), 0, card)
789
802
  else board.cards.push(card)
790
- if (fromTitle !== target.title) {
803
+ if (changedColumn) {
791
804
  record(board, { cardId: card.id, type: 'card_moved', source: actor, field: 'columnId', from: fromTitle, to: target.title, meta: { title: card.title } })
792
805
  }
793
806
  await save(workspace, session)
@@ -820,6 +833,8 @@ export function apply(ctx) {
820
833
  const previousId = board.completedColumnId
821
834
  if (previousId !== a.columnId) {
822
835
  board.completedColumnId = a.columnId
836
+ // Changing the definition of done does not establish when existing cards finished.
837
+ for (const card of board.cards) card.completedAt = null
823
838
  record(board, { cardId: null, type: 'board_completed_column_changed', source: actor, field: 'completedColumnId', from: previousId, to: a.columnId, meta: { fromColumn: findColumn(board, previousId)?.title ?? null, toColumn: findColumn(board, a.columnId)?.title ?? null } })
824
839
  await save(workspace, session)
825
840
  }
@@ -841,6 +856,7 @@ export function apply(ctx) {
841
856
  for (const card of board.cards) {
842
857
  if (card.columnId === id) {
843
858
  card.columnId = fallback
859
+ card.completedAt = fallback === board.completedColumnId ? new Date().toISOString() : null
844
860
  record(board, { cardId: card.id, type: 'card_moved', source: actor, field: 'columnId', from: deleted.title, to: board.columns[0].title, meta: { title: card.title } })
845
861
  }
846
862
  }
@@ -1142,7 +1158,7 @@ export function apply(ctx) {
1142
1158
  (card.label ? '[' + card.label + '] ' : '') +
1143
1159
  card.title +
1144
1160
  (card.dueDate ? ' (due ' + card.dueDate + ')' : '') +
1145
- (card.columnId === b.completedColumnId ? ' [completed]' : '') +
1161
+ (card.columnId === b.completedColumnId ? ' [completed; completedAt: ' + (card.completedAt || 'unknown') + ']' : '') +
1146
1162
  (card.commentCount ? ' (' + card.commentCount + ' comments)' : ''),
1147
1163
  )
1148
1164
  }
@@ -1155,7 +1171,7 @@ export function apply(ctx) {
1155
1171
  const tools = [
1156
1172
  {
1157
1173
  name: 'kanban_get',
1158
- description: 'Read the current state of the current project (workspace) kanban board (all lists, labels, cards with dueDate, and completedColumnId). Due dates are local calendar dates, not UTC timestamps; a date becomes overdue the following day. Cards in completedColumnId are finished and excluded from due-today/overdue checks. Resolve relative dates using the user local date and confirm the concrete YYYY-MM-DD date. Call it before planning to understand existing content and avoid duplicate cards.',
1174
+ description: 'Read the current state of the current project (workspace) kanban board (all lists, labels, cards with dueDate and completedAt, and completedColumnId). Due dates are local calendar dates, not UTC timestamps; a date becomes overdue the following day. Cards in completedColumnId are finished and excluded from due-today/overdue checks. completedAt is the latest completion UTC timestamp; null on a completed card means unknown. Resolve relative dates using the user local date and confirm the concrete YYYY-MM-DD date. Call it before planning to understand existing content and avoid duplicate cards.',
1159
1175
  parameters: { type: 'object', properties: {} },
1160
1176
  output: output(renderBoard),
1161
1177
  async execute(args, exec) {
@@ -1164,7 +1180,7 @@ export function apply(ctx) {
1164
1180
  },
1165
1181
  {
1166
1182
  name: 'kanban_get_card',
1167
- description: "Read one card's full details (title, raw Markdown description in note, label, priority, dueDate and comments), plus the board completion column ID from the current project (workspace) board by card id. Use kanban_get first to discover card ids; its summary omits note. Read this tool before editing an existing description to preserve its content and Markdown formatting.",
1183
+ description: "Read one card's full details (title, raw Markdown description in note, label, priority, dueDate, completedAt and comments), plus the board completion column ID from the current project (workspace) board by card id. completedAt is a system-managed UTC timestamp, cleared on reopening; null on a completed card means unknown. Use kanban_get first to discover card ids; its summary omits note. Read this tool before editing an existing description to preserve its content and Markdown formatting.",
1168
1184
  parameters: {
1169
1185
  type: 'object',
1170
1186
  properties: {
@@ -1198,6 +1214,7 @@ export function apply(ctx) {
1198
1214
  if (c.label) lines.push('Label: ' + c.label)
1199
1215
  if (c.dueDate) lines.push('Due date: ' + c.dueDate + ' (local calendar date)')
1200
1216
  lines.push('Completed: ' + (c.columnId === value.completedColumnId ? 'yes' : 'no'))
1217
+ if (c.columnId === value.completedColumnId) lines.push('Completed at: ' + (c.completedAt || 'unknown'))
1201
1218
  if (c.note) lines.push('Note: ' + c.note)
1202
1219
  if (Array.isArray(c.comments) && c.comments.length > 0) {
1203
1220
  lines.push('Comments:')
@@ -1335,7 +1352,7 @@ export function apply(ctx) {
1335
1352
  },
1336
1353
  {
1337
1354
  name: 'kanban_set_completed_column',
1338
- description: 'Choose the one list that means completed for this board by its stable column id, or clear the setting with null. Cards in this list are excluded from due-today and overdue checks. Existing boards require an explicit choice; never infer completion from a list name or position. New boards default to Done.',
1355
+ description: 'Choose the one list that means completed for this board by its stable column id, or clear the setting with null. Cards in this list are excluded from due-today and overdue checks. Existing boards require an explicit choice; never infer completion from a list name or position. New boards default to Done. Changing this setting clears completion timestamps; cards already in the new completion list have unknown completion times.',
1339
1356
  parameters: {
1340
1357
  type: 'object',
1341
1358
  properties: { columnId: { oneOf: [{ type: 'string' }, { type: 'null' }], description: 'Existing list id from kanban_get, or null to clear the completion column' } },