@goodandready/dsh-kanban 0.2.19 → 0.2.21

package/lib/webhook.js

@@ -1,23 +1,16 @@
-// Приём событий Gitea и GitHub.
-//
-// Вебхук даёт мгновенную сверку вместо ожидания следующего опроса. Опрос при
-// этом остаётся: вебхук может быть не настроен, недоступен снаружи или просто
-// потерян по дороге. Мгновенность — ускорение, а не замена надёжности.
-//
-// Модуль чистый: разбор и проверка подписи без сети и без хранилища.
+// Webhook ingestion for Gitea and GitHub.
+// Webhooks trigger immediate sync alongside periodic polling.
+// Pure module: parsing and signature verification without network or database.
 
 import { createHmac, timingSafeEqual } from 'node:crypto'
 
 /**
- * Проверить подпись доставки (поддерживает Gitea X-Gitea-Signature и GitHub X-Hub-Signature-256).
+ * Verify delivery signature (supports Gitea X-Gitea-Signature and GitHub X-Hub-Signature-256).
+ * Constant-time comparison to prevent timing attacks.
  *
- * Сравнение постоянного времени: обычное посимвольное сравнение по времени
- * ответа выдаёт, сколько первых байтов угадано, и подпись подбирается за
- * считанные попытки.
- *
- * @param {string} secret общий секрет
- * @param {string|Buffer} body сырое тело запроса
- * @param {string} signature значение заголовка X-Gitea-Signature или X-Hub-Signature-256
+ * @param {string} secret shared secret
+ * @param {string|Buffer} body raw request body
+ * @param {string} signature header value of X-Gitea-Signature or X-Hub-Signature-256
  */
 export function verifySignature(secret, body, signature) {
   if (!secret) return false
@@ -31,9 +24,9 @@ export function verifySignature(secret, body, signature) {
 }
 
 /**
- * Определить провайдера вебхука по входящим заголовкам запроса.
+ * Detect webhook provider from incoming request headers.
  *
- * @param {object} headers заголовки HTTP-запроса
+ * @param {object} headers HTTP request headers
  * @returns {'github'|'gitea'}
  */
 export function detectWebhookProvider(headers) {
@@ -45,11 +38,11 @@ export function detectWebhookProvider(headers) {
 }
 
 /**
- * Что за задачу затронуло событие.
+ * Identifies which task was affected by the event.
  *
- * Возвращается адрес задачи, а не готовое решение: решать, куда двинуть
- * карточку, — дело сверки, у которой перед глазами полная картина. Вебхук
- * только говорит «вот здесь что-то произошло, посмотри сейчас, а не потом».
+ * Returns task coordinates rather than a transition verdict: deciding
+ * where to move the card belongs to sync logic which holds the complete state.
+ * Webhook merely notifies: 'an event occurred here, inspect now'.
  *
  * @returns {{owner: string, repo: string, issueNumber?: number}|undefined}
  */
@@ -59,8 +52,8 @@ export function parseEvent(payload) {
   const repo = repository?.name
   if (typeof owner !== 'string' || owner === '' || typeof repo !== 'string' || repo === '') return undefined
 
-  // Номер issue приходит по-разному в зависимости от события; PR при этом сам
-  // является issue с тем же номером.
+  // Issue number format varies depending on event payload; PR is also an issue
+  // with matching number.
   const number = payload?.issue?.number
     ?? payload?.pull_request?.number
     ?? (typeof payload?.number === 'number' ? payload.number : undefined)

package/lib/workflow-bridge.js

@@ -1,15 +1,15 @@
-// Мост между карточками Kanban и встроенным в ядро DSH workflowEngine.
+// Bridge between Kanban cards and core DSH workflowEngine.
 //
-// Выполняет перенос логики из dsh-agent-orchestrator/lib/integrations/kanban-bridge.js:
-// 1. Сопоставление карточка ↔ роль (по меткам и колонкам).
-// 2. Выбор пресета агента с проверкой доступности через ctx.agentPresets.list()
-//    и фоллбэком на пресет по умолчанию.
-// 3. Формирование сценария и запуск через ctx.workflowEngine.start().
-// 4. Отслеживание жизненного цикла workflow/* (agent-start, agent-end, end):
+// Integrates card lifecycle with core workflowEngine:
+// 1. Map card <-> role (via labels and columns).
+// 2. Select agent preset with availability check via ctx.agentPresets.list()
+//    and fallback to default preset.
+// 3. Construct script and execute via ctx.workflowEngine.start().
+// 4. Track workflow/* lifecycle (agent-start, agent-end, end):
 //    - running -> review/done/failed;
-//    - фиксация runId и сессии в задаче;
-//    - отправка summary в связанный issue Gitea / GitHub.
-// 5. Отмена активного workflow по запросу из карточки.
+//    - record runId and session in task;
+//    - post summary to linked Gitea / GitHub issue.
+// 5. Cancel active workflow on card request.
 
 import { buildStartMessage, obtainAgent } from './launcher.js'
 import { applyMove } from './routes.js'
@@ -24,25 +24,25 @@ export const DEFAULT_COLUMN_ROLES = {
 }
 
 const LABEL_ROLE_PATTERNS = [
-  { role: 'spec', patterns: ['spec', 'specification', 'requirements', 'requirements-analysis', 'анализ', 'тз'] },
-  { role: 'architecture', patterns: ['architecture', 'архитектура', 'contract'] },
-  { role: 'ui_design', patterns: ['ui', 'ui_design', 'design', 'ux', 'дизайн'] },
-  { role: 'frontend', patterns: ['frontend', 'web', 'client', 'ui-impl', 'фронтенд'] },
-  { role: 'backend', patterns: ['backend', 'api', 'server', 'бэкенд'] },
+  { role: 'spec', patterns: ['spec', 'specification', 'requirements', 'requirements-analysis', 'analysis'] },
+  { role: 'architecture', patterns: ['architecture', 'contract'] },
+  { role: 'ui_design', patterns: ['ui', 'ui_design', 'design', 'ux'] },
+  { role: 'frontend', patterns: ['frontend', 'web', 'client', 'ui-impl'] },
+  { role: 'backend', patterns: ['backend', 'api', 'server'] },
   { role: 'fullstack', patterns: ['fullstack', 'full-stack', 'e2e'] },
-  { role: 'qa_tests', patterns: ['qa', 'qa_tests', 'test', 'tests', 'testing', 'verification', 'тест', 'тесты'] },
-  { role: 'bugfix', patterns: ['bug', 'bugfix', 'fix', 'баг', 'фикс'] },
-  { role: 'docs', patterns: ['docs', 'doc', 'documentation', 'документация'] },
-  { role: 'refactoring', patterns: ['refactor', 'refactoring', 'рефакторинг'] },
-  { role: 'research', patterns: ['research', 'spike', 'исследование'] },
-  { role: 'devops', patterns: ['devops', 'infra', 'ci', 'cd', 'deploy', 'деплой'] },
+  { role: 'qa_tests', patterns: ['qa', 'qa_tests', 'test', 'tests', 'testing', 'verification'] },
+  { role: 'bugfix', patterns: ['bug', 'bugfix', 'fix'] },
+  { role: 'docs', patterns: ['docs', 'doc', 'documentation'] },
+  { role: 'refactoring', patterns: ['refactor', 'refactoring'] },
+  { role: 'research', patterns: ['research', 'spike'] },
+  { role: 'devops', patterns: ['devops', 'infra', 'ci', 'cd', 'deploy'] },
 ]
 
 /**
- * Определить роль для задачи по меткам, колонке или явному полю role.
+ * Resolve role for task by labels, column or explicit role property.
  *
- * @param {object} task Задача доски
- * @returns {string} Идентификатор роли
+ * @param {object} task Board task
+ * @returns {string} Role ID
  */
 export function resolveRole(task) {
   if (!task) return 'backend'
@@ -81,14 +81,14 @@ export function resolveRole(task) {
 }
 
 /**
- * Подобрать пресет агента из доступных.
- * Если роль найдена в списке доступных пресетов — возвращает её.
- * Иначе выполняет безопасную деградацию на defaultPreset или undefined.
+ * Resolve agent preset from available list.
+ * If role matches available preset, returns it.
+ * Otherwise gracefully degrades to defaultPreset or undefined.
  *
  * @param {object} params
- * @param {string} params.role Имя роли
- * @param {Array<object|string>} [params.availablePresets] Список пресетов
- * @param {string} [params.defaultPreset] Пресет по умолчанию
+ * @param {string} params.role Role name
+ * @param {Array<object|string>} [params.availablePresets] Available presets
+ * @param {string} [params.defaultPreset] Default preset
  * @returns {string|undefined}
  */
 export function resolvePreset({ role, availablePresets = [], defaultPreset = undefined }) {
@@ -112,7 +112,7 @@ export function resolvePreset({ role, availablePresets = [], defaultPreset = und
 }
 
 /**
- * Построить JavaScript сценарий для ctx.workflowEngine.start().
+ * Construct JavaScript workflow script for ctx.workflowEngine.start().
  *
  * @param {object} params
  * @param {object} params.task
@@ -120,25 +120,27 @@ export function resolvePreset({ role, availablePresets = [], defaultPreset = und
  * @returns {string}
  */
 export function buildWorkflowScript({ task, role }) {
-  const taskId = String(task?.id || 'unknown').replace(/["\\]/g, '')
-  const safeRole = String(role || 'backend').replace(/["\\]/g, '')
-  const issueNum = task?.issueNumber ? `#${task.issueNumber}` : taskId
+  const rawRole = String(role || 'backend')
+  const rawTaskId = String(task?.id || 'unknown')
+  const validIssue = Number.isSafeInteger(task?.issueNumber) && task.issueNumber > 0 ? task.issueNumber : undefined
+  const cardLabel = validIssue !== undefined ? `#${validIssue}` : rawTaskId
+  const logMsg = `Starting phase ${rawRole} for card ${cardLabel}`
 
   return [
-    `phase("${safeRole}");`,
-    `log("Запуск этапа ${safeRole} по карточке ${issueNum}");`,
+    `phase(${JSON.stringify(rawRole)});`,
+    `log(${JSON.stringify(logMsg)});`,
     `const prompt = args.prompt;`,
-    `const result = await agent(prompt, { label: "${safeRole}", phase: "${safeRole}" });`,
+    `const result = await agent(prompt, { label: ${JSON.stringify(rawRole)}, phase: ${JSON.stringify(rawRole)} });`,
     `return {`,
-    `  role: "${safeRole}",`,
-    `  taskId: "${taskId}",`,
+    `  role: ${JSON.stringify(rawRole)},`,
+    `  taskId: ${JSON.stringify(rawTaskId)},`,
     `  summary: typeof result === 'string' ? result : (result ? JSON.stringify(result) : '')`,
     `};`,
   ].join('\n')
 }
 
 /**
- * Сформировать метаданные сценария workflow.
+ * Construct metadata for workflow script.
  *
  * @param {object} params
  * @param {object} params.task
@@ -160,7 +162,7 @@ export function buildWorkflowMeta({ task, role }) {
 }
 
 /**
- * Определить целевую колонку после успешного завершения этапа workflow.
+ * Determine target column upon successful completion of workflow phase.
  *
  * @param {string} currentCol
  * @returns {string}
@@ -177,7 +179,7 @@ export function resolveTargetColumn(currentCol) {
 }
 
 /**
- * Класс-мост между доской и встроенным сервисом workflow ядра DSH.
+ * Bridge class connecting Kanban board to core DSH workflow service.
  */
 export class WorkflowBridge {
   constructor({
@@ -206,7 +208,7 @@ export class WorkflowBridge {
   }
 
   /**
-   * Список зарегистрированных пресетов ядра.
+   * List of core registered presets.
    */
   async getAvailablePresets() {
     if (!this.agentPresets || typeof this.agentPresets.list !== 'function') {
@@ -215,13 +217,13 @@ export class WorkflowBridge {
     try {
       return await this.agentPresets.list()
     } catch (err) {
-      this.logger?.warn?.(`dsh-kanban: не удалось получить список пресетов: ${err.message}`)
+      this.logger?.warn?.(`dsh-kanban: failed to get presets list: ${err.message}`)
       return []
     }
   }
 
   /**
-   * Запуск workflow по карточке.
+   * Launch workflow for card.
    */
   async startTaskWorkflow({
     task,
@@ -317,7 +319,7 @@ export class WorkflowBridge {
     this.activeRuns.set(task.id, entry)
     this.runToTask.set(runId, task.id)
 
-    // Обновляем карточку в базе данных
+    // Update task card in database
     this.store.updateTask(task.id, {
       workflowRunId: runId,
       workflowStatus: 'running',
@@ -335,7 +337,7 @@ export class WorkflowBridge {
       fromCol: task.col || task.column,
       toCol: task.col || task.column,
       source: 'workflow',
-      detail: `запуск workflow ${runId} (роль: ${role}, пресет: ${preset || 'default'})`,
+      detail: `starting workflow ${runId} (role: ${role}, preset: ${preset || 'default'})`,
     })
 
     this.eventHub?.broadcast?.('task:change', {
@@ -347,7 +349,7 @@ export class WorkflowBridge {
       sessionId: taken.sessionId,
     })
 
-    // Асинхронное ожидание завершения run
+    // Asynchronously await run completion
     run.result.then(async (result) => {
       await this.handleWorkflowResult(task.id, runId, role, result)
     }).catch(async (err) => {
@@ -370,14 +372,14 @@ export class WorkflowBridge {
   }
 
   /**
-   * Отмена запущенного workflow.
+   * Cancel running workflow.
    */
   async cancelTaskWorkflow(taskId, reason = 'cancelled-by-user') {
     if (!taskId) return { cancelled: false, error: 'task-id-required' }
 
     const entry = this.activeRuns.get(taskId)
     if (!entry) {
-      // Возможно, статус в БД ещё числится running
+      // Status in DB might still indicate running
       const task = this.store.getTask(taskId)
       if (task?.workflowStatus === 'running') {
         this.store.updateTask(taskId, { workflowStatus: 'cancelled' })
@@ -398,7 +400,7 @@ export class WorkflowBridge {
       fromCol: entry.task?.col || entry.task?.column || 'progress',
       toCol: entry.task?.col || entry.task?.column || 'progress',
       source: 'workflow',
-      detail: `отмена workflow ${entry.runId}: ${reason}`,
+      detail: `cancelled workflow ${entry.runId}: ${reason}`,
     })
 
     this.eventHub?.broadcast?.('task:change', {
@@ -412,7 +414,7 @@ export class WorkflowBridge {
   }
 
   /**
-   * Обработка завершения выполнения workflow.
+   * Handle workflow execution completion.
    */
   async handleWorkflowResult(taskId, runId, role, result) {
     const entry = this.activeRuns.get(taskId)
@@ -443,16 +445,16 @@ export class WorkflowBridge {
           id: taskId,
           column: targetCol,
           source: 'workflow',
-          detail: `workflow ${runId} завершён успешно (роль: ${role})`,
+          detail: `workflow ${runId} completed successfully (role: ${role})`,
         })
       }
 
-      // Отправляем комментарий в связанный issue Gitea / GitHub
+      // Send comment to linked Gitea / GitHub issue
       if (this.git && task.repo && task.issueNumber) {
         const commentBody = [
-          `🚀 **Workflow завершён успешно!** (роль: \`${role}\`)`,
+          `🚀 **Workflow completed successfully!** (role: \`${role}\`)`,
           summary ? `\n${summary}` : '',
-          `\n*Статус карточки переведён в колонку "${targetCol}".*`,
+          `\n*Card status moved to column "${targetCol}".*`,
         ].filter(Boolean).join('\n')
 
         try {
@@ -464,16 +466,18 @@ export class WorkflowBridge {
             provider: task.provider,
           })
         } catch (err) {
-          this.logger?.warn?.(`dsh-kanban: не удалось отправить комментарий в issue ${task.repo}#${task.issueNumber}: ${err.message}`)
+          this.logger?.warn?.(`dsh-kanban: failed to comment on issue ${task.repo}#${task.issueNumber}: ${err.message}`)
         }
       }
 
-      // Добавляем комментарий в карточку
-      if (typeof this.store.addTaskComment === 'function' && summary) {
-        this.store.addTaskComment(taskId, {
-          author: 'workflow',
-          body: `🚀 **Workflow завершён (${role}):**\n\n${summary}`,
-        })
+      // Add comment to card
+      if (summary) {
+        const text = `🚀 **Workflow completed (${role}):**\n\n${summary}`
+        if (typeof this.store?.addComment === 'function') {
+          this.store.addComment(taskId, { author: 'workflow', role: 'workflow', text })
+        } else if (typeof this.store?.addTaskComment === 'function') {
+          this.store.addTaskComment(taskId, { author: 'workflow', role: 'workflow', text, body: text })
+        }
       }
     } else {
       this.store.addTransition({
@@ -481,7 +485,7 @@ export class WorkflowBridge {
         fromCol: task.col || task.column,
         toCol: task.col || task.column,
         source: 'workflow',
-        detail: `workflow ${runId} завершён со статусом ${stopReason}: ${result?.error || ''}`,
+        detail: `workflow ${runId} completed with status ${stopReason}: ${result?.error || ''}`,
       })
     }
 
@@ -489,7 +493,7 @@ export class WorkflowBridge {
       try {
         await entry.run.dispose()
       } catch (err) {
-        this.logger?.warn?.(`dsh-kanban: ошибка при dispose workflow run ${runId}: ${err.message}`)
+        this.logger?.warn?.(`dsh-kanban: error disposing workflow run ${runId}: ${err.message}`)
       }
     }
 
@@ -504,7 +508,7 @@ export class WorkflowBridge {
   }
 
   /**
-   * Подключить слушатели событий ядра workflow/*.
+   * Attach core workflow/* event listeners.
    *
    * @param {object} ctx Cordis context
    */
@@ -547,8 +551,8 @@ export class WorkflowBridge {
         const taskId = this.runToTask.get(runId)
         if (!taskId) return
 
-        // handleWorkflowResult также вызывается через run.result.then,
-        // но событие workflow/end гарантирует синхронизацию наблюдателей
+        // handleWorkflowResult is also invoked via run.result.then,
+        // but workflow/end event guarantees observer synchronization
         this.eventHub?.broadcast?.('task:change', {
           taskId,
           action: 'workflow-core-end',