@goodandready/dsh-kanban 0.2.18 → 0.2.20

package/lib/board-tool.js

@@ -1,18 +1,7 @@
-// Определение инструмента board_move — отдельно от обвязки cordis, чтобы
-// проверяться без харнесса и без `@deepseek-ai/dsh-tools`.
 //
-// Форма объекта задана контрактом `defineTool` из dsh-tools, и она НЕ является
 // JSON Schema:
 //
-//   parameters — карта «имя -> схема значения», без корня `type: 'object'`;
-//                необязательность выражается ОТСУТСТВИЕМ `required: true`
-//                (`required: false`, `optional` и `nullable` отвергаются);
-//   output     — обязателен: `defineTool` читает `options.output.render`
-//                безусловно, и без него падает не инструмент, а загрузка
-//                всего профиля.
 //
-// Схема объекта требует явного `additionalProperties`; здесь результат —
-// строка, поэтому схема строковая.
 
 import { COLUMN_ORDER as COLUMNS } from './config.js'
 import { resolveTransition } from './transitions.js'
@@ -20,33 +9,23 @@ import { TOOL_FORBIDDEN_COLUMNS } from './commands.js'
 import { parsePlan, applyPlan, serializePlan, planProgress, MAX_ITEMS } from './plan.js'
 
 /**
- * Колонки, доступные инструменту.
+ * Columns accessible by the tool.
  *
- * `done` вырезан из ПЕРЕЧИСЛЕНИЯ, а не только из проверки: подсказывать модели
- * значение, которое она получит отказом, — приглашение его попробовать.
+ * `done` is omitted from ENUM to prevent the model from attempting it.
  */
 const TOOL_COLUMNS = COLUMNS.filter((c) => !TOOL_FORBIDDEN_COLUMNS.includes(c))
 
 /**
- * Идентификатор сессии из контекста выполнения инструмента.
- *
- * dsh-tools переехал с `ctx.session` на `ctx.agent.session`. Читаем оба:
- * промах здесь не роняет ничего, он молча превращает инструмент в отказ
- * «за этой сессией нет карточки» — а такое ищут долго.
+ * Session ID from tool execution context.
+ * Reads both `ctx.session` and `ctx.agent.session` across dsh-tools versions.
  */
 export function sessionIdFromExec(exec) {
   return String(exec?.agent?.session?.id ?? exec?.session?.id ?? '')
 }
 
 /**
- * Задача сессии, с которой работает инструмент.
- *
- * Одна сессия может вести пачку. Пока задача одна — называть нечего. Как
- * только их несколько, инструмент ОБЯЗАН сказать, какую двигает: догадка тут
- * означает подвинутую не ту карточку, и заметят это нескоро.
- *
- * Ссылку принимаем в том виде, в каком агент её видит: `repo#номер` либо
- * идентификатор карточки.
+ * Task linked to session context.
+ * Accepts `repo#number` or task ID.
  *
  * @returns {{task: object}|{error: string}}
  */
@@ -72,14 +51,14 @@ export function pickTask(store, exec, ref) {
   return { task: found }
 }
 
-/** Как задача называется для агента: так же, как он видит её в сообщении. */
+/** Formatted task reference for agent. */
 function nameOf(task) {
   return task.repo && typeof task.issueNumber === 'number'
     ? `${task.repo}#${task.issueNumber}`
     : task.id
 }
 
-/** Определение board_move, готовое к передаче в `defineTool`. */
+/** board_move tool definition for `defineTool`. */
 export function boardMoveDefinition({ store, config }) {
   return {
     name: 'board_move',
@@ -110,7 +89,7 @@ export function boardMoveDefinition({ store, config }) {
       if (picked.error !== undefined) return picked.error
       const task = picked.task
 
-      // Проверка границ владения воркспейсом (#216)
+      // Workspace boundary verification (#216)
       const claimBoundaries = typeof config === 'function' ? config()?.workspaceClaimBoundaries : config?.workspaceClaimBoundaries
       if (claimBoundaries !== false && typeof task.workspaceId === 'string' && task.workspaceId.trim() !== '') {
         const sessionWs = String(exec?.agent?.session?.meta?.workspaceId ?? exec?.session?.meta?.workspaceId ?? '').trim()
@@ -118,8 +97,7 @@ export function boardMoveDefinition({ store, config }) {
           return `Cannot move card: task belongs to workspace "${task.workspaceId}", but current session belongs to workspace "${sessionWs}". Cross-workspace moves are restricted by workspaceClaimBoundaries.`
         }
       }
-      // Перечисление уже не предлагает `done`, но модель может прислать его
-      // мимо схемы, а завершение задачи не должно опираться на заявление.
+      // Model cannot transition directly to done without workflow validation
       if (column === 'done' || TOOL_FORBIDDEN_COLUMNS.includes(column)) {
         return 'The done column is a human-only acceptance boundary. A task is not finished by moving its card: move it to review for human acceptance; only a human can accept and move it to done.'
       }
@@ -147,13 +125,7 @@ export function boardMoveDefinition({ store, config }) {
 }
 
 /**
- * Определение board_plan, готовое к передаче в `defineTool`.
- *
- * План получаем прямо от агента, а не разбором его сообщений: разбор — это
- * гадание, а чужой `todo_list` завёл бы зависимость от соседнего плагина.
- *
- * Список пунктов необязателен. Агент публикует план один раз, а дальше двигает
- * только указатель: гонять весь список ради одного числа незачем.
+ * board_plan tool definition for `defineTool`.
  */
 export function boardPlanDefinition({ store }) {
   return {
@@ -179,9 +151,7 @@ export function boardPlanDefinition({ store }) {
       render: (_args, value) => [{ type: 'text', text: String(value) }],
     },
     async execute({ items, current }, exec) {
-      // План ОДИН на сессию: это план работы над пачкой, а не над каждой
-      // задачей порознь. Поэтому пишем его всем задачам сессии — иначе на
-      // карточках второй и третьей плана не будет вовсе.
+      // Plan is shared across session tasks
       const tasks = store.listTasksBySession(sessionIdFromExec(exec))
       if (tasks.length === 0) return 'This session has no kanban task behind it.'
       const task = tasks[0]
@@ -197,7 +167,7 @@ export function boardPlanDefinition({ store }) {
 }
 
 
-/** Определение board_checklist (#205) */
+/** board_checklist tool definition (#205) */
 export function boardChecklistDefinition({ store }) {
   return {
     name: 'board_checklist',
@@ -248,7 +218,7 @@ export function boardChecklistDefinition({ store }) {
   }
 }
 
-/** Определение board_report (#206) */
+/** board_report tool definition (#206) */
 export function boardReportDefinition({ store }) {
   return {
     name: 'board_report',
@@ -308,7 +278,7 @@ export function boardReportDefinition({ store }) {
   }
 }
 
-/** Определение board_comments (#208) */
+/** board_comments tool definition (#208) */
 export function boardCommentsDefinition({ store }) {
   return {
     name: 'board_comments',
@@ -336,7 +306,7 @@ export function boardCommentsDefinition({ store }) {
   }
 }
 
-/** Определение board_comment_add (#208) */
+/** board_comment_add tool definition (#208) */
 export function boardCommentAddDefinition({ store }) {
   return {
     name: 'board_comment_add',
@@ -368,7 +338,7 @@ export function boardCommentAddDefinition({ store }) {
   }
 }
 
-/** Определение board_decompose (#248) */
+/** board_decompose tool definition (#248) */
 export function boardDecomposeDefinition({ store, gitea }) {
   return {
     name: 'board_decompose',
@@ -458,7 +428,7 @@ export function boardDecomposeDefinition({ store, gitea }) {
   }
 }
 
-/** Определение board_checklist_item (#248) */
+/** board_checklist_item tool definition (#248) */
 export function boardChecklistItemDefinition({ store }) {
   return {
     name: 'board_checklist_item',