@goodandready/dsh-kanban 0.2.18 → 0.2.20

package/lib/sync.js

@@ -1,8 +1,8 @@
-// Сверка задач с Gitea и применение автопереходов.
+// Task synchronization with Gitea and automated column transitions.
 //
-// Ни таймера, ни планировщика здесь нет: когда сверять — решает `lib/index.js`.
-// Здесь только «сверить вот эти задачи и применить, что выведется». Поэтому
-// модуль проверяется тестами с заглушкой клиента, без сети и без ожиданий.
+// Timing and scheduling are managed by `lib/index.js`.
+// This module provides the pure synchronization logic, testable with mock clients
+// without network dependencies or wait timers.
 
 import { deriveColumn, resolveTransition, branchOfTask, pullsOfTask, resolveConflict } from './transitions.js'
 import { watchedRepos, shouldTake, archiveBefore, isWatched } from './intake.js'
@@ -10,9 +10,9 @@ import { colorsOfIssue } from './filters.js'
 import { issueToTask, issueBornAt, issueAuthor, issueAssignee, issueMilestone } from './import.js'
 
 /**
- * Выполнить операцию с экспоненциальной задержкой (exponential backoff) при сбоях сети.
+ * Execute an async operation with exponential backoff on network failures.
  * @template T
- * @param {() => Promise<T>} fn асинхронная операция
+ * @param {() => Promise<T>} fn async operation
  * @param {{retries?: number, baseMs?: number, maxMs?: number}} [opts]
  * @returns {Promise<T>}
  */
@@ -33,17 +33,11 @@ export async function withBackoff(fn, { retries = 2, baseMs = 50, maxMs = 500 }
 }
 
 /**
- * Наблюдения по одному репозиторию.
+ * Observations for a single repository (pull requests and branches).
  *
- * Читается ОДИН раз на репозиторий, а не на задачу: у десяти задач одного
- * репозитория наблюдения общие, и десять одинаковых запросов — это просто
- * десятикратная нагрузка на инстанс.
- *
- * Ошибка НЕ проглатывается. Неполное наблюдение хуже отсутствующего: не
- * прочитались PR — доска решит, что их нет, и увезёт карточку из ревью назад в
- * работу. Не прочитались ветки — сочтёт, что cleanup сделан, и объявит задачу
- * завершённой. Поэтому репозиторий с неудачным чтением пропускается до
- * следующей сверки целиком.
+ * Read once per repository rather than per task to minimize API calls.
+ * Failures are not silently swallowed: incomplete observations (missing PRs or branches)
+ * would lead to erroneous column transitions. If reading fails, the repository is skipped.
  */
 async function readRepo({ gitea, owner, repo }) {
   const [pulls, branches] = await Promise.all([
@@ -54,7 +48,7 @@ async function readRepo({ gitea, owner, repo }) {
 }
 
 /**
- * Что Gitea говорит про одну задачу.
+ * Observed state from Gitea for a single task.
  *
  * @returns {{column: string|undefined, branch: string|undefined, pull: object|undefined}}
  */
@@ -67,31 +61,24 @@ export function observeTask(task, repoState, issue) {
   return { column, branch, pull }
 }
 
-/** Пояснение к переходу — чтобы журнал читался, а не расшифровывался. */
+/** Human-readable explanation for automated column transitions. */
 export function explain({ column, branch, pull }) {
   switch (column) {
-    case 'review': return pull?.number ? `PR #${pull.number} снят с WIP` : 'PR готов к ревью'
-    case 'deploy': return pull?.number ? `PR #${pull.number} влит` : 'PR влит'
-    case 'cleanup': return branch ? `issue закрыт, ветка ${branch} ещё есть` : 'issue закрыт'
-    case 'done': return 'issue закрыт, ветка удалена'
-    case 'in-progress': return branch ? `появилась ветка ${branch}` : 'работа началась'
+    case 'review': return pull?.number ? `PR #${pull.number} ready for review` : 'PR ready for review'
+    case 'deploy': return pull?.number ? `PR #${pull.number} merged` : 'PR merged'
+    case 'cleanup': return branch ? `issue closed, branch ${branch} still exists` : 'issue closed'
+    case 'done': return 'issue closed, branch deleted'
+    case 'in-progress': return branch ? `branch ${branch} appeared` : 'work started'
     default: return ''
   }
 }
 
 /**
- * Поля, которые доска забирает у Gitea при каждой сверке.
- *
- * Метки и заголовок — источник правды в Gitea: переименовали issue или сменили
- * `priority/high` на `priority/critical` — доска обязана это увидеть, иначе
- * отбор по меткам работает по вчерашней разметке и молча врёт.
+ * Remote fields synced from Gitea on each reconciliation run.
  *
- * **Тело НЕ забираем.** Его правит и человек — заметкой из чипа, — и сверка,
- * затирающая тело каждые две минуты, съедала бы заметки. Тело обновляется по
- * кнопке «обновить», где это осознанное решение человека.
- *
- * Возвращаем только изменившееся: лишняя запись поднимает `updatedAt`, а по
- * нему разрешается спор о том, кто двигал задачу позже.
+ * Title, labels, author, assignee, milestone are updated if changed.
+ * Task body is deliberately NOT overwritten to preserve user notes made from the UI chip.
+ * Returns only modified fields to minimize unnecessary database writes.
  */
 function remoteFields(task, issue) {
   const patch = {}
@@ -103,22 +90,19 @@ function remoteFields(task, issue) {
     const same = names.length === (task.labels ?? []).length
       && names.every((n) => (task.labels ?? []).includes(n))
     if (!same) patch.labels = names
-    // Цвет метки в Gitea меняют реже имени, но меняют: сверка обязана
-    // подхватывать и его, иначе карточка красится по позавчерашней палитре.
+    // Label colors are updated if modified in Gitea.
     const colors = colorsOfIssue(issue.labels)
     const before = task.labelColors ?? {}
     const sameColors = Object.keys(colors).length === Object.keys(before).length
       && Object.entries(colors).every(([k, v]) => before[k] === v)
     if (!sameColors) patch.labelColors = colors
   }
-  // Дату заведения тоже подхватываем: карточки, приехавшие до этой правки,
-  // помнят день подхвата, и починить их может только сверка.
+  // Issue creation timestamp is updated to fix tasks imported prior to timestamp tracking.
   const born = issueBornAt(issue)
   if (born !== undefined && born !== task.createdAt) patch.createdAt = born
   const author = issueAuthor(issue)
   if (author !== '' && author !== task.author) patch.author = author
-  // Ответственного сверка подхватывает В ОБЕ стороны: назначили в Gitea —
-  // видно на доске, сняли — тоже видно.
+  // Assignee changes are synced bidirectionally (assigned or unassigned).
   if (issue?.assignee !== undefined || Array.isArray(issue?.assignees)) {
     const assignee = issueAssignee(issue)
     if (assignee !== (task.assignee ?? '')) patch.assignee = assignee
@@ -131,17 +115,13 @@ function remoteFields(task, issue) {
 }
 
 /**
- * Свести наблюдения и применить переход, если он нужен.
- *
- * Наблюдённые ветка и PR записываются в карточку независимо от того, случился
- * перевод или нет: это наблюдение о задаче, полезное само по себе.
+ * Apply observations and transition column if needed.
  *
- * Если обе стороны двигались с последней сверки, побеждает более позднее
- * изменение, а проигравшее ОБЯЗАТЕЛЬНО попадает в журнал задачи. Синхронизация,
- * тихо отменяющая правку человека, хуже отсутствующей: расхождение остаётся, а
- * узнать о нём неоткуда.
+ * Observed branch and PR are updated on the task regardless of whether column changes.
+ * Conflicts between local board edits and remote Gitea updates are resolved by timestamp,
+ * recording overridden changes in the transition history.
  *
- * @returns {object|undefined} применённый переход либо undefined
+ * @returns {object|undefined} applied transition or undefined
  */
 export function applyObservation({ store, task, observation, issue, remoteUpdatedAt, now = Date.now() }) {
   const patch = { syncedAt: now, ...remoteFields(task, issue) }
@@ -157,14 +137,14 @@ export function applyObservation({ store, task, observation, issue, remoteUpdate
   })
 
   if (verdict.winner === 'local') {
-    // Доска победила, но если Gitea говорил другое — молчать нельзя.
+    // Board won the conflict; log transition note if Gitea had a different column.
     if (verdict.overridden !== undefined) {
       store.addTransition({
         taskId: task.id,
         fromCol: task.column,
         toCol: task.column,
         source: 'gitea',
-        detail: `расхождение: Gitea считает «${verdict.overridden}», доска правилась позже`,
+        detail: `conflict: Gitea has "${verdict.overridden}", board edited later`,
       })
     }
     return undefined
@@ -183,20 +163,17 @@ export function applyObservation({ store, task, observation, issue, remoteUpdate
     toCol: move.column,
     source: move.source,
     detail: verdict.overridden !== undefined
-      ? `${move.detail} (перекрыто: на доске было «${verdict.overridden}»)`
+      ? `${move.detail} (overridden: board had "${verdict.overridden}")`
       : move.detail,
   })
   return move
 }
 
 /**
- * Сверить все задачи, за которыми стоит issue.
+ * Reconcile all tasks backed by an active Gitea issue.
  *
- * Ошибка по одной задаче не останавливает остальные: недоступный репозиторий —
- * причина пропустить его до следующей сверки, а не бросить всю доску.
- *
- * Отчёт называет НЕ ТОЛЬКО числа, но и причину первой неудачи: «сверено ноль
- * из пяти» человеку ничего не говорит, а «репозиторий не найден» говорит всё.
+ * A failure on one repository does not abort others; report identifies total counts
+ * and specific problem details.
  *
  * @returns {{checked: number, moved: number, failed: number,
  *   repos: number, reposFailed: number, problem: {where: string, message: string}|undefined}}
@@ -214,12 +191,10 @@ export async function syncAll({ gitea, store, logger, only, now = Date.now() })
   let moved = 0
   let failed = 0
   let reposFailed = 0
-  // Первая беда важнее последней: при протухшем токене все репозитории
-  // отвалятся одинаково, и показывать надо причину, а не последний по счёту
-  // репозиторий.
+  // Record first failure detail for clear error reporting.
   let problem
   const note = (where, error) => {
-    if (problem === undefined) problem = { where, message: String(error?.message ?? error ?? 'без причины') }
+    if (problem === undefined) problem = { where, message: String(error?.message ?? error ?? 'unknown error') }
   }
 
   for (const group of byRepo.values()) {
@@ -230,7 +205,7 @@ export async function syncAll({ gitea, store, logger, only, now = Date.now() })
       failed += group.tasks.length
       reposFailed += 1
       note(`${group.owner}/${group.repo}`, error)
-      logger?.warn?.(`dsh-kanban: репозиторий ${group.owner}/${group.repo} не прочитан: ${error?.message}`)
+      logger?.warn?.(`dsh-kanban: repository ${group.owner}/${group.repo} read failed: ${error?.message}`)
       continue
     }
 
@@ -246,7 +221,7 @@ export async function syncAll({ gitea, store, logger, only, now = Date.now() })
       } catch (error) {
         failed += 1
         note(`${task.owner}/${task.repo}#${task.issueNumber}`, error)
-        logger?.warn?.(`dsh-kanban: задача ${task.id} не сверена: ${error?.message}`)
+        logger?.warn?.(`dsh-kanban: task ${task.id} sync failed: ${error?.message}`)
       }
     }
   }
@@ -255,15 +230,10 @@ export async function syncAll({ gitea, store, logger, only, now = Date.now() })
 }
 
 /**
- * Какие репозитории опрашивать.
- *
- * Названные поимённо — их и берём. Пустой список означает ВСЕ репозитории
- * владельца: доска обязана показывать то, что есть в Gitea, а не то, что ей
- * перечислили руками.
+ * Resolve repositories to monitor for intake.
  *
- * Из всех берутся только те, где есть открытые задачи. Число приходит в том же
- * ответе, и отсев бесплатен: полсотни запросов впустую каждые две минуты — это
- * не осторожность, а расточительство.
+ * Returns explicitly configured repositories, or all organization repos with open issues
+ * if no explicit list is configured.
  *
  * @returns {Promise<Array<{owner: string, repo: string}>>}
  */
@@ -271,7 +241,7 @@ async function resolveRepos({ gitea, config, owner }) {
   const named = watchedRepos({ config, owner })
   if (named.length > 0) return named
   if (owner === undefined || owner === '') {
-    throw new Error('владелец не определён: назовите организацию в настройках')
+    throw new Error('owner not specified: set organization in settings')
   }
   const rows = await gitea.listOrgRepos({ owner })
   return rows
@@ -280,11 +250,7 @@ async function resolveRepos({ gitea, config, owner }) {
 }
 
 /**
- * Забрать из отслеживаемых репозиториев задачи, которых на доске ещё нет.
- *
- * Отказ по одному репозиторию не останавливает остальные — как и в сверке:
- * недоступный репозиторий это повод пропустить его до следующего прохода, а не
- * бросить всю доску.
+ * Ingest new issues from tracked repositories that do not yet exist on the board.
  *
  * @returns {{added: number, skipped: number, failed: number, problem: object|undefined}}
  */
@@ -294,8 +260,7 @@ export async function intakeAll({ gitea, store, config, owner, logger, only, rep
   let failed = 0
   let problem
 
-  // `only` сужает проход до одного репозитория: событие вебхука говорит про
-  // один, и полный обход означал бы обращение ко всем при каждом чихе в любом.
+  // Filter by single repository if requested (e.g. from webhook event).
   let repos
   try {
     repos = (given ?? await resolveRepos({ gitea, config, owner }))
@@ -303,7 +268,7 @@ export async function intakeAll({ gitea, store, config, owner, logger, only, rep
   } catch (error) {
     return {
       added, skipped, failed: 1,
-      problem: { where: 'список репозиториев', message: String(error?.message ?? error) },
+      problem: { where: 'repository list', message: String(error?.message ?? error) },
     }
   }
 
@@ -316,7 +281,7 @@ export async function intakeAll({ gitea, store, config, owner, logger, only, rep
       if (problem === undefined) {
         problem = { where: `${pair.owner}/${pair.repo}`, message: String(error?.message ?? error) }
       }
-      logger?.warn?.(`dsh-kanban: задачи из ${pair.owner}/${pair.repo} не забраны: ${error?.message}`)
+      logger?.warn?.(`dsh-kanban: tasks from ${pair.owner}/${pair.repo} fetch failed: ${error?.message}`)
       continue
     }
 
@@ -324,9 +289,7 @@ export async function intakeAll({ gitea, store, config, owner, logger, only, rep
       const verdict = shouldTake({ store, owner: pair.owner, repo: pair.repo, issue })
       if (!verdict.take) { skipped += 1; continue }
       store.createTask(issueToTask(issue, {
-        // Подхват всегда идёт на проектную доску: импорт issue на простую
-        // осознанно отвергается (README «Две доски»), и параметра доски здесь
-        // нет — он был мёртвым.
+        // Imported issues always go to the 'main' project board in the 'backlog' column.
         board: 'main', column: 'backlog', owner: pair.owner, repo: pair.repo,
       }))
       added += 1
@@ -337,10 +300,9 @@ export async function intakeAll({ gitea, store, config, owner, logger, only, rep
 }
 
 /**
- * Убрать в архив то, что достояло в «Выполнено» свой срок.
+ * Archive tasks that have remained in 'done' past the retention threshold.
  *
- * Не удаляет: удаление — отдельное решение человека, и оно на доске уже есть.
- * Архив обязан быть обратимым, иначе им не станут пользоваться из страха.
+ * Archiving is reversible (does not hard-delete).
  */
 export function archiveOverdue({ store, config, now = Date.now() }) {
   const before = archiveBefore({ now, afterDays: config?.archiveAfterDays })
@@ -351,14 +313,10 @@ export function archiveOverdue({ store, config, now = Date.now() }) {
 }
 
 /**
- * Состояние сверки для показа человеку.
- *
- * Живёт в памяти процесса, а не в базе: это положение текущего запуска, а не
- * свойство задач. После перезапуска честнее сказать «сверки ещё не было», чем
- * показать вчерашний успех как сегодняшний.
+ * In-memory sync status for UI telemetry.
  *
- * Неудача НЕ затирает время последнего успеха. Иначе теряется ответ на главный
- * вопрос — когда доска последний раз видела правду.
+ * Stored in process memory rather than SQLite to reflect current run state.
+ * Sync failures do not wipe the last successful sync timestamp.
  */
 export function createSyncState() {
   let okAt
@@ -369,7 +327,7 @@ export function createSyncState() {
   return {
     started() { running = true },
 
-    /** Записать итог прохода. */
+    /** Record sync run outcome. */
     finished(report) {
       running = false
       if (report?.problem === undefined) {
@@ -382,11 +340,11 @@ export function createSyncState() {
       problem = report.problem
     },
 
-    /** Сверка не начиналась вовсе — тоже беда, и своя. */
+    /** Record failure when sync cannot start. */
     failedToStart(where, message) {
       running = false
       failedAt = Date.now()
-      problem = { where, message: String(message ?? 'без причины') }
+      problem = { where, message: String(message ?? 'unknown error') }
     },
 
     snapshot() {

package/lib/templates.js

@@ -1,60 +1,60 @@
-// Шаблоны задач для быстрой постановки типовых работ (#220).
+// Task templates for rapid standard work decomposition (#220, #304).
 
 export const TASK_TEMPLATES = [
   {
     id: 'feature',
-    title: 'Новая функциональность (Feature)',
-    promptTemplate: 'Реализовать новую функциональность:\n- Цель:\n- Требования:\n- Границы изменений:',
+    title: 'New Feature',
+    promptTemplate: 'Implement new feature:\n- Goal:\n- Requirements:\n- Scope of changes:',
     checklist: [
-      { id: '1', text: 'Архитектурный план и дизайн-контракт согласованы', required: true, completed: false },
-      { id: '2', text: 'Код написан с соблюдением стандартов проекта', required: true, completed: false },
-      { id: '3', text: 'Написаны автоматические модульные/интеграционные тесты', required: true, completed: false },
-      { id: '4', text: 'Документация обновлена (README, docs/)', required: true, completed: false },
+      { id: '1', text: 'Architecture plan and design contract agreed', required: true, completed: false },
+      { id: '2', text: 'Code adheres to project guidelines and standards', required: true, completed: false },
+      { id: '3', text: 'Unit and integration tests added and passing', required: true, completed: false },
+      { id: '4', text: 'Documentation updated (README, docs/)', required: true, completed: false },
     ],
     priority: 'medium',
   },
   {
     id: 'bugfix',
-    title: 'Исправление ошибки (Bugfix)',
-    promptTemplate: 'Локализовать и исправить дефект:\n- Шаги воспроизведения:\n- Ожидаемое поведение:\n- Фактическое поведение:',
+    title: 'Bug Fix',
+    promptTemplate: 'Localize and resolve defect:\n- Reproduction steps:\n- Expected behavior:\n- Actual behavior:',
     checklist: [
-      { id: '1', text: 'Дефект воспроизведен изолированным тестом', required: true, completed: false },
-      { id: '2', text: 'Причина устранена без побочных эффектов', required: true, completed: false },
-      { id: '3', text: 'Регрессионный тест добавлен в test suite', required: true, completed: false },
+      { id: '1', text: 'Defect reproduced with isolated test case', required: true, completed: false },
+      { id: '2', text: 'Root cause fixed without regressions', required: true, completed: false },
+      { id: '3', text: 'Regression test added to test suite', required: true, completed: false },
     ],
     priority: 'high',
   },
   {
     id: 'refactor',
-    title: 'Рефакторинг и оптимизация (Refactoring)',
-    promptTemplate: 'Провести рефакторинг модуля без изменения внешнего поведения:\n- Целевой модуль:\n- Проблема архитектуры:\n- Критерии завершения:',
+    title: 'Refactoring & Optimization',
+    promptTemplate: 'Refactor module preserving external behavior:\n- Target module:\n- Architectural issue:\n- Completion criteria:',
     checklist: [
-      { id: '1', text: 'Покрыто существующими тестами (100% green)', required: true, completed: false },
-      { id: '2', text: 'Упрощена структура/устранен техдолг', required: true, completed: false },
-      { id: '3', text: 'Производительность не деградировала', required: true, completed: false },
+      { id: '1', text: 'Covered by existing tests (100% green)', required: true, completed: false },
+      { id: '2', text: 'Structure simplified and technical debt eliminated', required: true, completed: false },
+      { id: '3', text: 'Performance verified (no degradation)', required: true, completed: false },
     ],
     priority: 'low',
   },
   {
     id: 'security',
-    title: 'Аудит безопасности и зависимостей (Security)',
-    promptTemplate: 'Проверить безопасность и уязвимости зависимостей:\n- Область проверки:\n- Ревизия зависимостей:',
+    title: 'Security & Dependency Audit',
+    promptTemplate: 'Verify security and dependency vulnerabilities:\n- Audit scope:\n- Dependency revision:',
     checklist: [
-      { id: '1', text: 'Проверен supply-chain и лицензии зависимостей', required: true, completed: false },
-      { id: '2', text: 'Устранены известные CVE', required: true, completed: false },
-      { id: '3', text: 'Секреты и токены проверены на отсутствие утечек', required: true, completed: false },
+      { id: '1', text: 'Supply-chain and dependency licenses verified', required: true, completed: false },
+      { id: '2', text: 'Known CVEs mitigated or resolved', required: true, completed: false },
+      { id: '3', text: 'Secrets and credentials verified clean of leaks', required: true, completed: false },
     ],
     priority: 'high',
   },
   {
     id: 'release',
-    title: 'Подготовка и выпуск релиза (Release Prep)',
-    promptTemplate: 'Подготовить релиз пакета:\n- Версия:\n- Список изменений:\n- Проверки перед публикацией:',
+    title: 'Release Preparation',
+    promptTemplate: 'Prepare package release:\n- Version:\n- Changelog summary:\n- Pre-release verification:',
     checklist: [
-      { id: '1', text: 'Все тесты репозитория пройдены (npm test)', required: true, completed: false },
-      { id: '2', text: 'Совместимость с ядром подтверждена (npm run compat)', required: true, completed: false },
-      { id: '3', text: 'Размер упакованного пакета проверен (< 256 КБ)', required: true, completed: false },
-      { id: '4', text: 'Документация и changelog дополнены', required: true, completed: false },
+      { id: '1', text: 'All repository tests pass (npm test)', required: true, completed: false },
+      { id: '2', text: 'Core compatibility confirmed (npm run compat)', required: true, completed: false },
+      { id: '3', text: 'Package archive size verified (< 256 KiB)', required: true, completed: false },
+      { id: '4', text: 'Documentation and changelog updated', required: true, completed: false },
     ],
     priority: 'medium',
   },
@@ -62,4 +62,4 @@ export const TASK_TEMPLATES = [
 
 export function getTemplateById(id) {
   return TASK_TEMPLATES.find((t) => t.id === id)
-}
+}

package/lib/time.js

@@ -1,24 +1,18 @@
-// Относительное время для доски.
-//
-// Формат относительный, потому что «третий день» читается мгновенно, а точная
-// дата требует чтения и сравнения с сегодняшним числом. Скорость чтения тут и
-// есть смысл: на доску смотрят, чтобы за секунду понять, что застряло.
-//
-// Модуль отдаёт числа и единицу, а не готовую строку: собирает и переводит её
-// браузерная половина.
+// Relative time formatting for board.
+// Returns duration values; frontend translates and renders them.
 
 const MINUTE = 60_000
 const HOUR = 60 * MINUTE
 const DAY = 24 * HOUR
 
 /**
- * Насколько давно это было.
+ * How long ago the timestamp occurred.
  *
- * Будущее (расхождение часов между машинами) не выдумываем «через N минут», а
- * считаем настоящим моментом: показывать доске будущее незачем.
+ * Future timestamps are clamped to present moment.
+ * Board does not project future timestamps.
  *
  * @returns {{unit: 'now'|'min'|'hour'|'day', value: number}|undefined}
- *   `undefined` — отметки времени нет.
+ *   `undefined` - no timestamp.
  */
 export function relativeParts(now, then) {
   if (typeof then !== 'number' || !Number.isFinite(then) || then <= 0) return undefined
@@ -30,11 +24,8 @@ export function relativeParts(now, then) {
 }
 
 /**
- * Пора ли тревожиться о молчании задачи.
- *
- * Отдельного опроса живости сессий не заводим: это второй источник правды и
- * лишняя нагрузка. Смотрим на то, что и так знаем, — когда задачу последний
- * раз трогали.
+ * Whether task has been idle past threshold.
+ * Relies on last activity timestamp rather than active pinging.
  */
 export function isStale({ now, updatedAt, sessionId, afterMinutes }) {
   const limit = Number(afterMinutes)