@goodandready/dsh-kanban 0.2.19 → 0.2.20

package/lib/routes.js

@@ -1,12 +1,9 @@
-// Обработчики HTTP доски.
+// HTTP route handlers for the board.
 //
-// Браузерная половина не имеет доступа ни к хранилищу, ни к службам хоста —
-// она ходит сюда. Обработчики написаны так, чтобы проверяться без HTTP:
-// принимают разобранный вход и хранилище, возвращают объект ответа. Обвязка
-// вокруг req/res живёт в `lib/index.js`.
-//
-// Перехвата чужих маршрутов и промежуточных обработчиков в DSH нет:
-// `ctx.webServer.register` — единственный способ.
+// The client bundle runs in the browser without direct access to SQLite or host services;
+// it interacts with these handlers. Handlers accept parsed inputs and the store instance,
+// returning response objects to facilitate testing without full HTTP server setups.
+// Request/response wrapper integration lives in `lib/index.js`.
 
 import { COLUMN_ORDER, columnsOf, wipLimitField, columnNamesOf } from './config.js'
 import { parsePlan, planItems, planProgress, taskState, queuePosition } from './plan.js'
@@ -16,7 +13,7 @@ import { facetsOf, facetsOfTask, groupByRepo, sortByLife } from './filters.js'
 import { parseBody } from './markdown.js'
 import { computeNextRun } from './cron.js'
 
-/** Больше этого тело запроса не читаем: без предела один запрос кладёт хост. */
+/** Maximum request payload size to prevent denial of service. */
 export const MAX_BODY_BYTES = 256 * 1024
 
 function isLoopbackAddress(addr) {
@@ -28,17 +25,16 @@ function isLoopbackAddress(addr) {
 }
 
 /**
- * Запрос с чужого сайта. Изменяющие маршруты правят локальное состояние, и
- * пускать в них кросс-сайтовый запрос нельзя (#261).
- * Защита требует:
- * 1. Наличие безопасного sec-fetch-site ('same-origin', 'same-site', 'none').
- * 2. Совпадение origin и host (если origin передан).
- * 3. Loopback-источник (remoteAddress: 127.0.0.1, ::1, ::ffff:127.0.0.1).
+ * Cross-site request validation (#261).
+ * Mutating endpoints modify local state and reject cross-site requests:
+ * 1. Safe sec-fetch-site ('same-origin', 'same-site', 'none').
+ * 2. Origin matches host header (when origin is present).
+ * 3. Loopback remoteAddress (127.0.0.1, ::1, ::ffff:127.0.0.1).
  */
 export function isTrustedRequest(req) {
   if (!req || !req.headers) return false
 
-  // 1. Проверка sec-fetch-site (отсутствие или cross-site запрещены)
+  // 1. Verify sec-fetch-site header (missing or cross-site rejected)
   const site = req.headers['sec-fetch-site']
   if (!site || site === 'cross-site') {
     return false
@@ -47,7 +43,7 @@ export function isTrustedRequest(req) {
     return false
   }
 
-  // 2. Сверка origin с host
+  // 2. Validate origin against host
   const origin = req.headers.origin
   if (origin !== undefined) {
     if (origin === 'null') return false
@@ -60,7 +56,7 @@ export function isTrustedRequest(req) {
     }
   }
 
-  // 3. Проверка loopback remoteAddress
+  // 3. Verify loopback remoteAddress
   const remote = req.socket?.remoteAddress || req.connection?.remoteAddress
   if (remote && !isLoopbackAddress(remote)) {
     return false
@@ -69,7 +65,7 @@ export function isTrustedRequest(req) {
   return true
 }
 
-/** Разобрать `/dsh-kanban/task/<id>[/<action>]`; иначе undefined. */
+/** Parse `/dsh-kanban/task/<id>[/<action>]`; returns undefined if non-matching. */
 export function parseTaskPath(pathname) {
   const m = /^\/dsh-kanban\/task\/([^/]+)(?:\/([a-z-]+))?\/?$/.exec(pathname ?? '')
   if (m === null) return undefined
@@ -77,19 +73,14 @@ export function parseTaskPath(pathname) {
 }
 
 /**
- * Задача с разобранным планом и состоянием.
- *
- * Сырую строку плана наружу не отдаём: браузерная половина — отдельный бандл,
- * она не может позвать `lib/plan.js`, и разбор пришлось бы писать второй раз.
+ * Enrich task with parsed plan, state, and filters.
  *
- * `liveOf` возвращает состояние живого агента сессии либо `undefined`, если
- * агента нет. Без него состояние не вычислить: «остановился» — это факт об
- * отсутствии агента, а не догадка по тишине.
+ * Plan is pre-parsed on server because client bundle cannot import `lib/plan.js`.
+ * `liveOf` returns active agent state or undefined if session is inactive.
  */
 function withPlan(task, liveOf, config, now, sameSession) {
   const plan = parsePlan(task.plan)
-  // Отказ реестра — это «агента нет», а не повод не собрать доску: одна
-  // непрочитанная сессия не должна прятать от человека все задачи.
+  // Registry error implies agent unavailable; do not fail whole board render.
   let live
   try {
     if (typeof liveOf === 'function' && task.sessionId) live = liveOf(task.sessionId)
@@ -98,57 +89,44 @@ function withPlan(task, liveOf, config, now, sameSession) {
     ...task,
     plan: { items: planItems(plan), progress: planProgress(plan) },
     state: taskState({ task, live }),
-    // Номер в очереди считается на лету: агент берёт задачи одну за другой, и
-    // у оставшихся третий сам становится вторым.
+    // Queue position calculated dynamically across active tasks in same session.
     queuePos: queuePosition(task, sameSession),
-    // Метки разобраны здесь же: браузер сверяет списки, а не разбирает строки.
+    // Label facets extracted on server for consistent client filtering.
     facets: facetsOfTask(task),
-    // Считаем здесь, а не в браузере: порог живёт в настройках, а настройки —
-    // на хосте. Отдавать браузеру ещё и порог значило бы отдавать ему решение.
+    // Stale calculation performed on host where configuration resides.
     stale: isStale({
       now,
       updatedAt: task.updatedAt,
       sessionId: task.sessionId,
       afterMinutes: config?.staleAfterMin,
     }),
-    // Просрочено — дедлайн есть и он раньше «сейчас». Считается на хосте,
-    // чтобы браузер не зависел от своих часов.
+    // Overdue calculated on host using server clock.
     overdue: typeof task.dueAt === 'number' && task.dueAt > 0 && task.dueAt < now,
   }
 }
 
-/** Разложить задачи: по колонкам, внутри — по проектам, внутри — идущее наверх. */
+/** Order tasks: by column, grouped by repository, with active tasks on top. */
 function orderForBoard(tasks, columns) {
   const out = []
   for (const column of columns) {
     const inColumn = tasks.filter((t) => t.column === column)
     for (const group of groupByRepo(sortByLife(inColumn))) out.push(...group.tasks)
   }
-  // Задачи в колонке, которой на этой доске нет, не теряем: спрятать их совсем
-  // хуже, чем показать в непривычном месте.
+  // Retain tasks in columns not visible on current board to prevent data loss.
   const seen = new Set(out.map((t) => t.id))
   for (const task of tasks) if (!seen.has(task.id)) out.push(task)
   return out
 }
 
 /**
- * Ответ доски: колонки в фиксированном порядке, задачи и пределы.
- * Порядок колонок задан кодом, а не настройками: он повторяет воркфлоу, и
- * переставлять его местами незачем.
+ * Build board response payload: columns in canonical order, tasks, and limits.
  */
 export function buildBoard({ store, config, board = 'main', repo, liveOf, sync, projectRoot }) {
-  // Одно «сейчас» на всю сборку: иначе соседние карточки посчитались бы по
-  // разным моментам, и разница вылезла бы ровно на границе минуты.
+  // Uniform timestamp across snapshot calculation.
   const now = Date.now()
-  // Порядок задаём здесь, а не в браузере: правила группировки и подъёма
-  // повторять во второй раз значило бы завести вторую их редакцию.
-  //
-  // Отдаём задачи УЖЕ разложенными — сперва по проектам, внутри проекта идущая
-  // работа наверх. Браузер рисует заголовок при смене проекта, и после отбора
-  // группы остаются целыми, потому что отбор порядка не меняет.
+  // Tasks are sorted and grouped on server: repo grouping with active items first.
   const raw = store.listTasks({ board, repo })
-  // Очередь считается внутри своей сессии, а не по доске целиком: две сессии —
-  // две независимые очереди.
+  // Queue position scoped per session.
   const bySession = new Map()
   for (const task of raw) {
     const id = typeof task.sessionId === 'string' ? task.sessionId : ''
@@ -167,34 +145,28 @@ export function buildBoard({ store, config, board = 'main', repo, liveOf, sync,
     columnsOf(store.boardKind(board)),
   )
   const kind = store.boardKind(board)
-  // Своё название приходит с сервера, а перевод остаётся на браузере: конфиг
-  // живёт здесь, а языки — там, и смешивать их не надо.
+  // Column custom names sent from server; locale translation handled by client.
   const names = columnNamesOf(config)
   const columns = columnsOf(kind).map((id) => {
     const count = tasks.filter((t) => t.column === id).length
     const limit = wipLimitField(config, id)
     return { id, name: names[id], count, limit, overLimit: limit !== undefined && count > limit }
   })
-  // Отборы считаем по ВСЕМ задачам доски, а не по отобранным: счётчик рядом со
-  // значением отвечает «сколько там всего», а не «сколько осталось после моего
-  // же выбора».
+  // Filter counts calculated over all tasks on board.
   return {
     board, kind, now, boards: store.listBoards(), columns, tasks,
-    // Фактический корень проектов: {path, set} — путь и признак «задан
-    // настройкой». Считается на хосте — браузер не знает ни настройку, ни cwd.
+    // Resolved project root {path, set} computed on host.
     projectRoot: projectRoot ?? { path: '', set: false },
 
     facets: facetsOf(tasks),
-    // Состояние сверки едет вместе с доской: отдельный опрос ради него был бы
-    // вторым источником обращений и вторым местом, где это может отстать.
+    // Sync telemetry state attached directly to board snapshot.
     sync: sync ?? { state: 'never' },
   }
 }
 
 /**
- * Перенос карточки. Предел колонки — предупреждение, а не запрет: перенос
- * выполняется, а признак превышения уезжает в ответ, и доска подсветит
- * колонку. Запрет здесь превратил бы предел из ориентира в преграду.
+ * Card move transition. WIP limit is advisory: move executes, and exceeded status
+ * is returned for UI highlighting.
  */
 export function applyMove({ store, config, id, column, beforeId, afterId, source = 'manual', detail = '' }) {
   const before = store.getTask(id)
@@ -210,14 +182,12 @@ export function applyMove({ store, config, id, column, beforeId, afterId, source
   return { task, overLimit: limit !== undefined && count > limit }
 }
 
-/** Создание своей задачи (не из Gitea). */
+/** Create local board task (not linked to Gitea). */
 export function createTask({ store, input }) {
   const title = typeof input?.title === 'string' ? input.title.trim() : ''
   if (title === '') return { error: 'title-required', status: 400 }
   const board = input?.board ?? 'main'
-  // Колонка проверяется по ВИДУ доски, а не по общему списку: положить задачу
-  // в `deploy` на простой доске значило бы спрятать её в колонке, которой там
-  // нет.
+  // Validate column against board kind; simple boards do not have deploy/cleanup.
   const allowed = columnsOf(store.boardKind(board))
   const column = allowed.includes(input?.column) ? input.column : 'backlog'
   const task = store.createTask({
@@ -230,7 +200,7 @@ export function createTask({ store, input }) {
   return { task }
 }
 
-/** Правка полей карточки. Колонку и порядок правит только перенос. */
+/** Update card fields. Column transitions are handled via applyMove. */
 export function updateTask({ store, id, input }) {
   const current = store.getTask(id)
   if (current === undefined) return { error: 'task-not-found', status: 404 }
@@ -238,12 +208,9 @@ export function updateTask({ store, id, input }) {
   if (typeof input?.title === 'string' && input.title.trim() !== '') patch.title = input.title.trim()
   if (typeof input?.body === 'string') patch.body = input.body
   if (Array.isArray(input?.labels)) patch.labels = input.labels.filter((l) => typeof l === 'string')
-  // Приоритет — локальное свойство доски: в Gitea назад не пишется. Чужие
-  // значения отбрасываются: одно испорченное поле не должно ронять правку
-  // остальных.
+  // Priority is local to board and not synced back to Gitea.
   if (PRIORITIES.includes(input?.priority)) patch.priority = input.priority
-  // Дедлайн — тоже локальное свойство. Ноль снимает, положительное число —
-  // ставит; отрицательное и мусор отбрасываются.
+  // Deadline is local. 0 clears deadline; positive value sets it.
   if (typeof input?.dueAt === 'number' && Number.isFinite(input.dueAt) && input.dueAt >= 0) {
     patch.dueAt = Math.floor(input.dueAt)
   }
@@ -273,17 +240,12 @@ export function confirmPermission({ store, id }) {
   return { task: store.updateTask(id, { permissionConfirmedAt: Date.now() }) }
 }
 
-/** Известные приоритеты. Пустой — «без приоритета». */
+/** Known priority values. Empty string indicates unprioritized. */
 const PRIORITIES = ['', 'high', 'medium', 'low']
 
 /**
- * Дописать заметку в тело задачи.
- *
- * Именно в тело, а не в отдельную ленту заметок и не комментарием в Gitea:
- * владелец выбрал самый простой из трёх смыслов, и он же самый дешёвый.
- *
- * Дописываем на сервере, а не в браузере: чип держит копию задачи, и склейка
- * у него потеряла бы всё, что тело нажило с момента её получения.
+ * Append note to task body.
+ * Handled on server to prevent overwriting edits made elsewhere.
  */
 export function appendNote({ store, id, input }) {
   const task = store.getTask(id)
@@ -295,10 +257,8 @@ export function appendNote({ store, id, input }) {
 }
 
 /**
- * Убрать карточку в архив или вернуть на доску.
- *
- * Возврат ставит её ровно туда, где она была: колонка и порядок сохранены, а
- * `archivedAt` — единственное, что менялось.
+ * Archive or unarchive card.
+ * Unarchiving restores card to its original column and position.
  */
 export function setArchived({ store, id, archived, now = Date.now() }) {
   const task = store.getTask(id)
@@ -306,16 +266,14 @@ export function setArchived({ store, id, archived, now = Date.now() }) {
   return { task: store.setArchived(id, archived ? now : 0) }
 }
 
-/** Архив: свой список, а не колонка — архив стадией работы не является. */
+/** Query archived tasks list. */
 export function listArchive({ store }) {
   return { tasks: store.listArchived() }
 }
 
 /**
- * Назначить ответственного или снять назначение.
- *
- * Пустой логин — это снятие, а не отказ: «никто» такое же законное состояние
- * задачи, как и любой исполнитель.
+ * Assign task or clear assignment.
+ * Empty login unassigns the task.
  *
  * @returns {{task: object}|{error: string, status: number}}
  */
@@ -330,7 +288,7 @@ export function assignTask({ store, id, login }) {
     fromCol: task.column,
     toCol: task.column,
     source: 'manual',
-    detail: who === '' ? 'ответственный снят' : `ответственный: ${who}`,
+    detail: who === '' ? 'unassigned' : `assigned: ${who}`,
   })
   return { task: store.getTask(id) }
 }
@@ -342,18 +300,11 @@ export function deleteTask({ store, id }) {
 }
 
 /**
- * Тело задачи, разобранное в дерево блоков.
- *
- * Разбираем здесь, а не в браузере: браузерная половина — отдельный бандл и
- * позвать `lib/markdown.js` не может. Заодно тело не едет в разметку строкой,
- * и подставить туда чужое нечем.
+ * Parse task markdown body into structured block elements.
+ * Done on server so client bundle does not need markdown parser.
  */
 /**
- * Метрики доски: где стоит работа и что залежалось.
- *
- * Считается по журналу переходов и ничего не записывает. Порог «залежалось»
- * приходит запросом, а не настройкой: это вопрос, который задают по-разному в
- * разные дни, а не свойство доски.
+ * Board metrics: WIP distribution and stale tasks.
  *
  * @returns {{columns: object[], done: object, stale: object[], tasks: number}}
  */
@@ -380,10 +331,8 @@ export function boardMetrics({ store, board = 'main', now = Date.now(), staleDay
 }
 
 /**
- * Можно ли предлагать «продолжить работу».
- *
- * Только когда сессия у задачи записана, а живого агента за ней нет: у живой
- * продолжать нечего, у задачи без сессии — нечего возобновлять.
+ * Check whether a task can be resumed.
+ * Eligible when task has recorded sessionId but no active agent is running.
  */
 export function canRevive(task, live) {
   const has = typeof task?.sessionId === 'string' && task.sessionId !== ''
@@ -401,14 +350,13 @@ export function taskLog({ store, id }) {
   return { transitions: store.listTransitions(id) }
 }
 
-/** Задача, привязанная к сессии; отсутствие задачи — штатный ответ. */
+/** Find task associated with session; absence is normal response. */
 export function taskBySession({ store, sessionId, agents }) {
   const task = store.findTaskBySession(sessionId)
   if (task === undefined) return { task: null }
   let live
   try { live = agents?.get?.(sessionId) } catch { live = undefined }
-  // Вид доски едет вместе с задачей: чип предлагает колонки, а предлагать
-  // `deploy` задаче с простой доски значит звать в колонку, которой нет.
+  // Board kind returned with task so UI displays matching column choices.
   return {
     task,
     columns: columnsOf(store.boardKind(task.board)),
@@ -417,21 +365,14 @@ export function taskBySession({ store, sessionId, agents }) {
 }
 
 /**
- * Полный снимок доски для бэкапа/переноса.
- *
- * Отдаём всё, что есть в хранилище: доски, задачи (включая архивные) и журнал
- * переходов. Импорт восстанавливает это как есть.
+ * Export full board snapshot for backup or migration.
  */
 export function exportBoard({ store }) {
   return store.exportAll()
 }
 
 /**
- * Восстановить доску из снимка.
- *
- * Идемпотентно: существующая задача с тем же id не перезаписывается, а
- * пропускается — повторный импорт не плодит дубли. Доски создаются, если их
- * ещё нет.
+ * Restore board from backup snapshot (idempotent; skips existing IDs).
  *
  * @returns {{imported: number, skipped: number, error?: string}}
  */
@@ -491,28 +432,28 @@ export function importBoard({ store, input }) {
 }
 
 /**
- * Экспорт задач в Excel-совместимый CSV с UTF-8 BOM (#223).
+ * Export tasks to Excel-compatible CSV with UTF-8 BOM (#223).
  *
  * @param {{store: object, board?: string}} options
- * @returns {string} CSV-строка с префиксом \uFEFF
+ * @returns {string} CSV string with UTF-8 BOM prefix
  */
 export function exportTasksCsv({ store, board = 'main' }) {
   const tasks = store.listTasks({ board })
   const headers = [
     'ID',
-    'Заголовок',
-    'Колонка',
-    'Приоритет',
-    'Репозиторий',
+    'Title',
+    'Column',
+    'Priority',
+    'Repository',
     'Issue #',
-    'Исполнитель',
-    'Модель',
-    'Провайдер',
-    'Глубина рассуждения',
-    'Воркспейс',
-    'Ветка',
-    'Создана',
-    'Обновлена',
+    'Assignee',
+    'Model',
+    'Provider',
+    'Reasoning Effort',
+    'Workspace',
+    'Branch',
+    'Created',
+    'Updated',
   ]
 
   function escapeCsv(val) {
@@ -554,13 +495,13 @@ export function exportTasksCsv({ store, board = 'main' }) {
     rows.push(row.join(','))
   }
 
-  // Префикс UTF-8 BOM для Microsoft Excel
+  // UTF-8 BOM prefix for Microsoft Excel
   return '\uFEFF' + rows.join('\r\n')
 }
 
 
 /**
- * Очистить воркдерево задачи.
+ * Clean up task worktree.
  */
 export async function handleCleanupWorktree({ store, task, workspaceRegistry, force, cleanupTaskWorktree }) {
   if (!task) return { status: 404, body: { error: 'task-not-found' } }
@@ -574,7 +515,7 @@ export async function handleCleanupWorktree({ store, task, workspaceRegistry, fo
 }
 
 /**
- * Получить diff рабочей копии задачи.
+ * Get working copy diff for task.
  */
 export async function handleTaskDiff({ task, getTaskDiff }) {
   if (!task) return { status: 404, body: { error: 'task-not-found' } }
@@ -583,7 +524,7 @@ export async function handleTaskDiff({ task, getTaskDiff }) {
 }
 
 /**
- * Получить список коммитов задачи.
+ * Get commit list for task.
  */
 export async function handleTaskCommits({ task, getTaskCommits }) {
   if (!task) return { status: 404, body: { error: 'task-not-found' } }
@@ -592,7 +533,7 @@ export async function handleTaskCommits({ task, getTaskCommits }) {
 }
 
 /**
- * Слить воркдерево задачи и перевести в done.
+ * Merge task worktree branch and transition to done.
  */
 export async function handleTaskMerge({ store, task, targetBranch, workspaceRegistry, mergeTaskWorktree }) {
   if (!task) return { status: 404, body: { error: 'task-not-found' } }
@@ -613,13 +554,13 @@ export async function handleTaskMerge({ store, task, targetBranch, workspaceRegi
     fromCol: task.column,
     toCol: 'done',
     source: 'manual',
-    detail: `принята и смержена ветка ${task.branch} в ${mergeResult.targetBranch}`,
+    detail: `accepted and merged branch ${task.branch} into ${mergeResult.targetBranch}`,
   })
   return { status: 200, body: { task: updated, merged: true, targetBranch: mergeResult.targetBranch } }
 }
 
 /**
- * Проверить статус воркдерева задачи (ветка, dirty, воркспейс).
+ * Check task worktree status (branch, dirty files, workspace).
  */
 export async function handleTaskWorktreeStatus({ task, checkWorktreeDirty }) {
   if (!task) return { status: 404, body: { error: 'task-not-found' } }
@@ -637,7 +578,7 @@ export async function handleTaskWorktreeStatus({ task, checkWorktreeDirty }) {
 }
 
 /**
- * Обновить DoD чеклист задачи.
+ * Update Definition of Done checklist for task.
  */
 export function handleTaskChecklist({ store, task, input }) {
   if (!task) return { status: 404, body: { error: 'task-not-found' } }
@@ -647,7 +588,7 @@ export function handleTaskChecklist({ store, task, input }) {
 }
 
 /**
- * Установить отчёт выполнения задачи.
+ * Set completion report for task.
  */
 export function handleTaskReport({ store, task, input }) {
   if (!task) return { status: 404, body: { error: 'task-not-found' } }
@@ -656,7 +597,7 @@ export function handleTaskReport({ store, task, input }) {
 }
 
 /**
- * Получить комментарии задачи.
+ * Get comments for task.
  */
 export function handleGetTaskComments({ task }) {
   if (!task) return { status: 404, body: { error: 'task-not-found' } }
@@ -664,7 +605,7 @@ export function handleGetTaskComments({ task }) {
 }
 
 /**
- * Добавить комментарий к задаче.
+ * Add comment to task.
  */
 export function handleAddTaskComment({ store, task, input }) {
   if (!task) return { status: 404, body: { error: 'task-not-found' } }
@@ -676,7 +617,7 @@ export function handleAddTaskComment({ store, task, input }) {
 }
 
 /**
- * Принять задачу на ревью (перевод в done).
+ * Accept task review (transition to done).
  */
 export function handleAcceptTask({ store, task }) {
   if (!task) return { status: 404, body: { error: 'task-not-found' } }
@@ -685,7 +626,7 @@ export function handleAcceptTask({ store, task }) {
 }
 
 /**
- * Отклонить задачу на ревью (перевод обратно в in_progress).
+ * Reject task review (return to in_progress).
  */
 export function handleRejectTask({ store, task, input }) {
   if (!task) return { status: 404, body: { error: 'task-not-found' } }
@@ -696,7 +637,7 @@ export function handleRejectTask({ store, task, input }) {
 }
 
 /**
- * Сохранить дамп прогресса задачи.
+ * Save task progress dump snapshot.
  */
 export function handleProgressDump({ store, task, input, formatProgressDump }) {
   if (!task) return { status: 404, body: { error: 'task-not-found' } }